@utilitywarehouse/hearth-react-native 0.34.4 → 0.35.0

package/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Derivative Works, and to permit persons to whom the Derivative Works
+      is furnished to do so.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of
+      any other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in use. Please also include a
+      reference to the disclaimer of Section 7 and 8.
+
+   Copyright 2026 Utility Warehouse
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,52 @@
+# React Native
+
+## Releases
+
+Currently all `v0` releases should be considered unstable pre-releases. Any
+breaking change will be made in a minor release, with the number of breaking
+changes per minor release kept to a minimum. All breaking changes will be
+documented with guidelines for how to update your code, and, if necessary,
+will be accompanied by a codemod.
+
+## AI Assistant Setup
+
+`@utilitywarehouse/hearth-react-native` ships with an AI skill file that gives
+your coding assistant deep knowledge of the component library — including
+component APIs, usage patterns, design tokens, and best practices.
+
+## Setup
+
+After installing the package, run the init command to wire it up for your AI tool:
+
+```bash
+npx @utilitywarehouse/hearth-react-native init-ai
+```
+
+This detects your AI tool's config file and adds the skill reference automatically.
+
+### Manual setup
+
+If you prefer to add it yourself, append the appropriate line to your project's AI config file:
+
+| Tool                  | Config file                       | Line to add                                                                                       |
+| --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Claude Code           | `CLAUDE.md`                       | `@node_modules/@utilitywarehouse/hearth-react-native/SKILL.md`                                    |
+| Cursor                | `.cursorrules`                    | `@node_modules/@utilitywarehouse/hearth-react-native/SKILL.md`                                    |
+| Windsurf              | `.windsurfrules`                  | `@node_modules/@utilitywarehouse/hearth-react-native/SKILL.md`                                    |
+| Codex / OpenAI agents | `AGENTS.md`                       | `See node_modules/@utilitywarehouse/hearth-react-native/SKILL.md for component usage guidelines.` |
+| GitHub Copilot        | `.github/copilot-instructions.md` | `See node_modules/@utilitywarehouse/hearth-react-native/SKILL.md for component usage guidelines.` |
+| Cline / Roo           | `.clinerules`                     | `@node_modules/@utilitywarehouse/hearth-react-native/SKILL.md`                                    |
+
+## What the skill covers
+
+- Component inventory and when to use each one
+- Utility props, variants, and composition patterns
+- Design token usage and Unistyles theming
+- Accessibility requirements and patterns
+- Common mistakes and anti-patterns
+
+## Keeping it up to date
+
+The skill file is versioned with the package — upgrading
+`@utilitywarehouse/hearth-react-native` automatically updates the skill. No
+changes needed to your config file after the initial setup.

package/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: hearth-react-native
+description: Use when building any UI component or screen with the Hearth React Native library. Use this implicitly whenever building any UI component or screen in a React Native app that has Hearth React Native installed — Hearth React Native is the default. Do not wait for an explicit mention of "Hearth React Native" — if it's UI work in an app with Hearth React Native, use this skill. Triggers when creating components, implementing Figma designs, adding UI features, or writing any React Native code in the app.
+---
+
+# Building with Hearth React Native
+
+You are acting as a React Native engineer. Your job is to turn requirements —
+either Figma designs or written requirements — into UI React Native code using
+Hearth — Utility Warehouse's Design Systems libraries.
+
+## Package imports
+
+| Purpose    | Package                                       |
+| ---------- | ---------------------------------------------- |
+| Components | `@utilitywarehouse/hearth-react-native`       |
+| Icons      | `@utilitywarehouse/hearth-react-native-icons` |
+
+## Before you implement: discover what exists
+
+There are 2 options for discovering existing components and documentation:
+
+- MCP server: `hearth-react-native` MCP hosted on a remote URL
+- Raw markdown files: located in the `public` folder of the `hearth-react-native` package
+
+**Default to the raw markdown files.** They are local, always available, and
+version-matched to what the app actually has installed — so the API you read is
+the API you get.
+
+**Use the MCP server for richer exploration** — searching across components,
+fetching story code, or discovering what exists when you're not sure where to
+start. It's worth reaching for when the markdown files don't give you enough
+context, but it requires the server to be configured and reachable.
+
+Whatever source you use, review what is available before writing any code.
+
+The library is broad — always check whether an existing component covers the
+need before implementing anything custom.
+
+### Raw markdown files
+
+Full component API reference is available in the installed package. First,
+resolve where it is installed — in a monorepo the package is typically hoisted
+to the repo root rather than the app's local `node_modules`:
+
+node -e "const path = require('path'); console.log(path.dirname(require.resolve('@utilitywarehouse/hearth-react-native/package.json')))"
+
+The docs are then at:
+
+- `<hearth-react-native-root>/public/llms/components/` — one file per component
+- `<hearth-react-native-root>/public/llms/docs/` — design tokens, styling, layout, hooks, dark mode
+- `<hearth-react-native-root>/public/llms.txt` — index of all available docs
+
+### MCP Server
+
+You can use the **`hearth-react-native`** MCP server if available (`https://main--68e3ad5c6e80b57678cad6c6.chromatic.com/mcp`):
+
+1. `list-all-documentation` — get an index of all Hearth React Native components
+2. `get-documentation` — get props, API, and usage examples for a specific component
+3. `get-documentation-for-story` — get story code and docs for a specific story
+
+## Plan before writing
+
+For anything beyond a trivial change — a new screen, a multi-component feature, an
+unfamiliar part of the codebase — share a brief plan before writing code:
+
+- Which Hearth components you'll use and why
+- Any local components you'll need
+- The output folder/file structure
+- Any decisions where multiple reasonable options exist
+
+For small, self-contained tasks (adding a button, tweaking a layout) you can
+proceed directly. Use your judgement: if you'd want sign-off as a developer
+pairing with someone, ask for it here too.
+
+---
+
+# Principles
+
+1. **Use Hearth React Native.** (`@utilitywarehouse/hearth-react-native`) This is
+   the default component library for Utility Warehouse React Native apps. Use it
+   for all UI work unless explicitly told otherwise.
+2. **Use available components first.** Check documentation for what is available
+   before writing custom UI, or reaching for bare React Native primitives.
+3. **Compose, don't reinvent.** Most screens can be built by composing existing
+   layout and UI components and utilising utility props. Only create new
+   components or custom Unistyles styles when absolutely necessary.
+4. **Use built-in variants and utility props, before custom Unistyles.**
+   `variant="outline"`, `size="sm"`, `p="200"`, `rounded="lg"` — only reach for a
+   custom `StyleSheet.create` when these don't achieve the desired result.
+5. **Use semantic colors.** The `color`, `iconColor`, `backgroundColor` (and `bg`/
+   `bgColor` shorthands) utility props resolve against simplified semantic tokens
+   (e.g. `color="primary"`, `bg="brand"`) — don't reach for raw palette values
+   (`theme.color.purple[400]`) unless a semantic token doesn't cover the case.
+6. **Theme tokens in Unistyles `StyleSheet.create`, not hardcoded values.** Any
+   custom styling should pull from the `theme` argument (`theme.space`,
+   `theme.color`, `theme.font`, `theme.borderRadius`) rather than hardcoded hex
+   codes or font sizes. Prefer tokens for pixel dimensions too, but a hardcoded
+   value (e.g. a `minHeight` with no matching token) is fine when no token
+   covers the case — check the theme first rather than treating this as an
+   absolute rule.
+7. **Space tokens are for spacing only** — do not use spacing tokens for
+   one-off dimensions that aren't part of the spacing scale.
+
+# Critical Rules
+
+## Use layout components
+
+Use layout components to structure and space content. Do not add margin to
+individual UI elements to achieve spacing — keep spacing decisions at the layout
+level so UI components stay composable.
+
+Five layout primitives, all built on design tokens:
+
+| Component   | Use for                                                                                            |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| `Box`       | Generic container (renders a `View`); supports all utility props — spacing, sizing, colour, flex/position etc. |
+| `Flex`      | Flexbox layouts — rows, columns, centring, wrapping                                                 |
+| `Grid`      | Grid layouts — responsive column counts                                                             |
+| `Center`    | `Box` pre-configured with `alignItems="center"` and `justifyContent="center"`                       |
+| `Container` | Page-width container with responsive gutters and vertical spacing                                   |
+
+```tsx
+// Box with utility props (shorthand + full names both work)
+<Box bg="brand" p="200" borderRadius="md">
+  <BodyText color="inverted">Content</BodyText>
+</Box>
+
+// Flex column with gap
+<Flex direction="column" gap="200">
+  <Heading>Title</Heading>
+  <BodyText>Content</BodyText>
+</Flex>
+
+// Responsive grid columns
+<Grid columns={{ base: 1, md: 2, lg: 3 }} spacing="md">
+  <Box>{...}</Box>
+  <Box>{...}</Box>
+</Grid>
+
+// Centered content
+<Center>
+  <Spinner />
+</Center>
+```
+
+Use `gap` (or the `spacing`/`space` alias) on the parent `Flex`/`Grid` to space
+children. For distribution and alignment, use `justify`/`align` on `Flex`. Don't
+put margin on individual sibling components just for spacing.
+
+```tsx
+// ❌ WRONG — margin for spacing
+<Flex>
+  <Button mr="100">Cancel</Button>
+  <Button>Submit</Button>
+</Flex>
+
+// ✅ CORRECT — gap on parent
+<Flex gap="100">
+  <Button>Cancel</Button>
+  <Button>Submit</Button>
+</Flex>
+```
+
+`Box` accepts the full set of utility props (shorthand and full names), for
+example: `p`/`padding`, `px`/`paddingHorizontal`, `m`/`margin`, `h`/`height`,
+`w`/`width`, `bg`/`backgroundColor`, `rounded`/`borderRadius`, plus every other
+`ViewStyle` property directly (`flex`, `alignItems`, `position`, `opacity`,
+etc.). `Flex` and `Grid` accept the same spacing/sizing/colour utility props
+alongside their own layout-specific props (`direction`, `align`, `justify`,
+`wrap` on `Flex`; `columns` on `Grid`).
+
+## Styling: Unistyles, not `StyleSheet` from `react-native`
+
+Custom styles use `react-native-unistyles`'s `StyleSheet.create(theme => ({...}))`,
+re-exported from the package. Only reach for this when utility props and
+existing component variants don't cover the need.
+
+- Define styles as **variants** (e.g. `size`, `colorScheme`, `variant`,
+  `disabled`) and apply them at render time via `styles.useVariants({...})`.
+- Use **`compoundVariants`** for combinations that need distinct treatment,
+  rather than conditional logic in the component body.
+- Read colours, spacing, radii, and typography from the `theme` parameter
+  (`theme.color.*`, `theme.space[...]`, `theme.borderRadius.*`, `theme.font.*`)
+  rather than hardcoding a hex value or font family. Prefer a token for pixel
+  dimensions too, but check the theme first before assuming one doesn't
+  exist — existing components do fall back to a hardcoded value (e.g. a
+  `minHeight`) when there's genuinely no matching token.
+- `_web` blocks hold web-only pseudo-class styles (`_hover`, `_focus-visible`,
+  `_active`) since Unistyles targets both native and `react-native-web`
+  (Storybook renders through `react-native-web`, so these matter for how a
+  component looks there).
+
+```tsx
+const ButtonRoot = ({ variant = 'solid', size = 'md', disabled = false, ...props }) => {
+  styles.useVariants({ variant, size, disabled });
+
+  return <Pressable {...props} style={styles.container} />;
+};
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    borderRadius: theme.components.button.borderRadius,
+    gap: theme.components.button.gap,
+    _web: {
+      '_focus-visible': {
+        outlineStyle: 'solid',
+        outlineWidth: 2,
+        outlineColor: theme.color.focus.primary,
+      },
+    },
+    variants: {
+      disabled: {
+        true: { opacity: theme.opacity.disabled },
+      },
+      variant: {
+        solid: { borderColor: theme.color.interactive.highlight.border.strong },
+        outline: { backgroundColor: 'transparent', borderWidth: 2 },
+      },
+      size: {
+        sm: { minHeight: 32 },
+        md: { minHeight: 48 },
+      },
+    },
+    compoundVariants: [
+      {
+        variant: 'solid',
+        size: 'sm',
+        styles: { paddingHorizontal: theme.space['150'] },
+      },
+    ],
+  },
+}));
+```
+
+## Responsive breakpoints
+
+Breakpoints are configured once (via Unistyles' `StyleSheet.configure`) and
+cascade **mobile-first**: a value applies from that breakpoint upward until
+overridden by a larger one. See the
+[Unistyles breakpoints reference](https://www.unistyl.es/v3/references/breakpoints/)
+for the underlying behaviour.
+
+Hearth's breakpoints are `base`, `xs`, `sm`, `md`, `lg`, `xl`, `superLarge`,
+`tvLike` — **not** the web package's `mobile`/`tablet`/`desktop`/`wide` names.
+`base` is the required starting point (must map to the smallest screen size)
+and behaves like `mobile` does on web: never omit it from a responsive object,
+or nothing applies at the smallest breakpoint.
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  container: {
+    // ❌ WRONG — no style applied below `md`
+    padding: { md: theme.space['400'] },
+
+    // ✅ CORRECT
+    padding: { base: theme.space['200'], md: theme.space['400'] },
+  },
+}));
+```
+
+`Grid`'s `columns` prop takes the same breakpoint keys directly:
+`columns={{ base: 1, md: 2, lg: 3 }}`.
+
+## Required app-level providers
+
+Hearth React Native components rely on these wrapping the app root:
+
+- `GestureHandlerRootView` (from `react-native-gesture-handler`) — required for
+  any gesture-driven component (`BottomSheet`, `Modal`, `Select`, swipeable
+  `Toast`, etc.).
+- `BottomSheetModalProvider` (from Hearth) — required for any component built on
+  a bottom sheet (`Modal`, `Combobox`, `Select`, `Menu`, `DatePicker`,
+  `TimePicker`).
+
+```tsx
+import { BottomSheetModalProvider } from '@utilitywarehouse/hearth-react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+const App = () => (
+  <GestureHandlerRootView>
+    <BottomSheetModalProvider>{/* app content */}</BottomSheetModalProvider>
+  </GestureHandlerRootView>
+);
+```
+
+If a screen renders one of these components and the app crashes or the sheet
+fails to present, check these providers are wired up before debugging further.
+
+## Safe area handling
+
+Two different patterns exist depending on the component — check which one
+applies before reaching for `react-native-safe-area-context` directly:
+
+- **Bottom-sheet-based components** (`Modal`, `Combobox`, `Select`, and the
+  `BottomSheet*` primitives) don't take their own safe-area prop — they read a
+  boolean `useSafeAreaInsets` (default `true`) from the nearest
+  `BottomSheetModalProvider` via context, which toggles whether their internal
+  `SafeAreaView` applies the `top` edge. Set `useSafeAreaInsets={false}` on
+  `BottomSheetModalProvider` only if the parent screen already handles
+  safe-area insets itself — don't look for the prop on the individual
+  components.
+- **`NavModal`** (used when a screen is already presented by React Navigation)
+  reads safe-area insets directly from the Unistyles runtime
+  (`rt.insets.top`/`rt.insets.bottom` inside `StyleSheet.create((theme, rt) =>
+  ...)`) rather than rendering a `SafeAreaView`.
+
+Don't wrap Hearth components in your own `SafeAreaView` on top of these —
+check `BottomSheetModalProvider`'s `useSafeAreaInsets` prop (or `NavModal`'s
+own prop, for that component) first.
+
+## Accessibility
+
+Accessibility is not optional — the UW product is used by customers across a
+wide range of abilities, and assistive technology support is a product
+requirement. Use React Native's accessibility props, not ARIA/web semantics:
+
+- `accessibilityRole`, `accessibilityLabel`, `accessibilityHint`,
+  `accessibilityState` — Hearth wires these where it can (e.g. `Heading`
+  always sets `accessibilityRole="header"`), so in most cases you just need to
+  use the components correctly and avoid overriding what they do.
+- For form inputs wrapped in `FormField`, don't hand-roll
+  `accessibilityLabel`/`accessibilityHint` — `FormField` and its inputs
+  already combine the label, helper text, and required/invalid state into the
+  correct accessibility props via the `useFormFieldAccessibility` hook.
+- Use `accessibilityState={{ checked, disabled }}` (not custom props) on
+  toggle-like components so screen readers report state correctly.
+
+## Compound components
+
+Many components have sub-components that must be used together. Read the
+reference file before composing. Examples:
+
+- `Card` → `CardContent`, `CardActions`, `CardAction*`, `CardPressHandler`
+- `Accordion` → `AccordionItem`, `AccordionTrigger`, `AccordionHeader`,
+  `AccordionContent`
+- `FormField` → `FormFieldLabel`, `FormFieldHelper`, `FormFieldValid`,
+  `FormFieldInvalid`
+
+Compound components share state via a `<Component>Context` (check for a
+`useXContext` export) rather than prop drilling.
+
+## Common patterns
+
+### Themed images that adapt to light/dark mode
+
+```tsx
+<ThemedImage light={require('./logo-light.png')} dark={require('./logo-dark.png')} />
+```
+
+### Full-width button on mobile, auto-width on larger screens
+
+Control width with the parent layout component rather than a prop on `Button`.
+
+```tsx
+<Flex direction="column" align={{ base: 'stretch', md: 'flex-start' }}>
+  <Button variant="solid" colorScheme="highlight">
+    Submit
+  </Button>
+</Flex>
+```

package/build/components/Alert/AlertIcon.js

@@ -20,10 +20,10 @@ const AlertIcon = (props) => {
 AlertIcon.displayName = 'AlertIcon';
 const styles = StyleSheet.create(theme => ({
     icon: {
-        width: 24,
-        height: 24,
-        minWidth: 24,
-        minHeight: 24,
+        width: theme.components.icon.md.width,
+        height: theme.components.icon.md.height,
+        minWidth: theme.components.icon.md.width,
+        minHeight: theme.components.icon.md.height,
         alignSelf: 'flex-start',
         variants: {
             colorScheme: {

package/build/components/Badge/BadgeIcon.js

@@ -10,10 +10,10 @@ const BadgeIcon = (props) => {
 BadgeIcon.displayName = 'BadgeIcon';
 const styles = StyleSheet.create(theme => ({
     icon: {
-        width: 20,
-        height: 20,
-        minWidth: 20,
-        minHeight: 20,
+        width: theme.components.icon.sm.width,
+        height: theme.components.icon.sm.height,
+        minWidth: theme.components.icon.sm.width,
+        minHeight: theme.components.icon.sm.height,
         variants: {
             colorScheme: {
                 info: {},

package/build/components/Card/CardAction/CardActionIcon.js

@@ -12,8 +12,8 @@ CardActionIcon.displayName = 'CardActionIcon';
 const styles = StyleSheet.create(theme => ({
     icon: {
         color: theme.color.icon.primary,
-        width: 24,
-        height: 24,
+        width: theme.components.icon.md.width,
+        height: theme.components.icon.md.height,
     },
 }));
 export default CardActionIcon;

package/build/components/Card/CardAction/CardActionTrailingIcon.js

@@ -12,8 +12,8 @@ CardActionTrailingIcon.displayName = 'CardActionTrailingIcon';
 const styles = StyleSheet.create(theme => ({
     icon: {
         color: theme.color.icon.primary,
-        minWidth: 20,
-        minHeight: 20,
+        minWidth: theme.components.icon.sm.width,
+        minHeight: theme.components.icon.sm.height,
     },
 }));
 export default CardActionTrailingIcon;

package/build/components/Carousel/CarouselControlItem.js

@@ -15,8 +15,8 @@ const CarouselControlItem = createPressable({
 CarouselControlItem.displayName = 'CarouselControlItem';
 const styles = StyleSheet.create(theme => ({
     item: {
-        width: 24,
-        height: 24,
+        width: theme.components.icon.md.width,
+        height: theme.components.icon.md.height,
         alignItems: 'center',
         justifyContent: 'center',
     },