name: react-native-uswds description: Build or modify React Native and Expo apps using the U.S. Web Design System (USWDS) design language. Use when (1) implementing UI with rn-uswds-components or a USWDS-mirroring RN library, (2) mapping USWDS design tokens to React Native theme/spacing/colors, (3) choosing or styling USA-prefixed components (Button, Alert, Card, form controls, Modal, Table, etc.), (4) theming or customizing USWDS tokens in RN, or (5) ensuring accessibility and government-style consistency in RN screens.

React Native USWDS

Build React Native/Expo UIs that mirror the U.S. Web Design System (USWDS) using design tokens and USA-prefixed components. Token values and component behavior in this skill align with the official web system and with the implementation in ./rn-uswds-components.

Official USWDS references

• Design system site: designsystem.digital.gov — components, guidance, examples.
• GitHub (source): github.com/uswds/uswds — Sass/CSS/JS, packages, tokens.
• Design tokens: designsystem.digital.gov/design-tokens/ — color, spacing, typesetting, shadow, z-index.
• Components overview: designsystem.digital.gov/components/overview/ — full component list and descriptions.
• Theme color tokens: designsystem.digital.gov/design-tokens/color/theme-tokens/ — primary, secondary, accent, base hex values.

Use these when checking web USWDS behavior, token semantics, or accessibility expectations. For a curated link list and when to use each, see references/official-links.md.

When this skill applies

• App uses or will use rn-uswds-components (or similar RN USWDS library) under ./rn-uswds-components or equivalent.
• Tasks involve theme tokens (colors, spacing, typography, radius, shadow, z-index), component selection (Button, Alert, Card, Accordion, form controls, Modal, List, Table, Breadcrumb, Pagination, Typography, Banner, SiteAlert, Grid), or integration (Provider, imports, Pressable/Reanimated patterns).

Core conventions

• Theme: Use useUSWDSTheme() or USWDSThemeProvider for token access. Never hardcode USWDS values; use theme.colors, theme.units(n), theme.spacing, theme.fontSizes, theme.radius, theme.shadow, theme.zIndex.
• Components: Prefer USA-prefixed exports (USAButton, USACard, USATextInput, etc.) from the library. Use Pressable (not TouchableOpacity) for custom tap targets; use Reanimated for press feedback (scale/opacity) when available.
• Styling: Use StyleSheet.create; avoid inline style objects for static styles. Use theme tokens for colors and spacing.

Implementation notes (from ./rn-uswds-components)

• Library layout: theme/ (tokens, ThemeContext), hooks/ (e.g. usePressAnimation), components/<Name>/ (Component.tsx + index.ts), root index.ts barrel.
• Web vs native: Interactive components branch on Platform.OS === 'web' — on web they use state-based opacity (no Reanimated transform) to avoid DOM issues; on native they use usePressAnimation (scale + opacity via Reanimated).
• Press feedback: Shared hook usePressAnimation({ scaleActive?, opacityActive? }) returns animatedStyle, onPressIn, onPressOut. Defaults: scale 0.97, opacity 0.92. Use for any custom pressable that should match library feel.
• Accessibility: Components set accessibilityRole (e.g. button, link, checkbox, radio) and accessibilityLabel / accessibilityState where appropriate; preserve these when wrapping.
• Theme override: USWDSThemeProvider accepts partial theme; it is merged with defaults. Override only the keys you need (e.g. colors.primary).

Quick reference

| Need | Use | |------|-----| | Spacing | theme.units(n) (8px base) or theme.spacing['2'], theme.spacing.card, etc. | | Colors | theme.colors.primary, theme.colors['base-dark'], theme.colors.error, etc. | | Buttons | USAButton (variant: primary, secondary, outline, accent, base, danger, ghost; size: big, medium, small) | | Forms | USATextInput, USACheckbox, USARadio, USASelect (label, error, hint where applicable) | | Feedback | USAAlert (info/success/warning/error), USASiteAlert, USABanner | | Layout | USAGrid (maxWidth, paddingX/Y), USACard, USASummaryBox, USAList | | Overlay | USAModal (visible, onClose, title, primaryAction, secondaryAction) | | Data/nav | USATable, USABreadcrumb, USAPagination, USAAccordion | | Typography | USATypography (variant: h1–h6, body, lead, small) |

Integration checklist

1. Ensure peer deps: react, react-native, react-native-reanimated.
2. Optionally wrap app with USWDSThemeProvider to override tokens (e.g. theme={{ colors: { primary: '#custom' } }}).
3. Import from the library barrel (e.g. from '../rn-uswds-components' or the project path).
4. Use USA components as-is; extend or wrap only when necessary. Prefer component props over custom wrappers that duplicate token usage.

Rules

| Rule | Impact | Description | |------|--------|-------------| | theme-use-tokens | HIGH | Use theme tokens for all USWDS values; never hardcode. | | components-usa-prefix | HIGH | Prefer USA-prefixed library components. | | accessibility-preserve | HIGH | Preserve accessibilityRole/Label/State when wrapping. | | styling-style-sheet | MEDIUM | Use StyleSheet.create and theme for static styles. | | platform-web-fallback | MEDIUM | On web use opacity-only press feedback. | | provider-theme-override | MEDIUM | Override theme via USWDSThemeProvider with partial theme. | | pressable-not-touchable | MEDIUM | Use Pressable (and usePressAnimation on native). | | imports-barrel | LOW | Import from library barrel. |

For full rule text and incorrect/correct examples, see each rule file under rules/. For a single compiled guide for agents/LLMs, see AGENTS.md.

Resources

• Agent guide: AGENTS.md — compiled rules, refs, quick reference for automation.
• Token mapping and component list: references/tokens-and-components.md — full token tables and component APIs.
• Official USWDS links: references/official-links.md — when to use each official doc/site.