@utilitywarehouse/hearth-react-native 0.34.4 → 0.35.0

package/{docs/styling.mdx → public/llms/docs/styling.md}

@@ -1,9 +1,3 @@
-import { Meta } from '@storybook/addon-docs/blocks';
-import { BackToTopButton, NextPrevPage } from './components';
-
-<Meta title="Styling" />
-<BackToTopButton />
-
 # Styling
 
 Hearth React Native uses [Unistyles](https://www.unistyl.es/) for styling components and exposes the library
@@ -49,6 +43,7 @@ Some of the key features of Unistyles include:
 To start using Unistyles for styling your components, simply import the `StyleSheet` from Hearth React Native:
 
 ```tsx
+// Example usage
 import { StyleSheet, View, Text } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
@@ -82,6 +77,7 @@ Hearth React Native comes with a comprehensive set of design tokens that ensure
 To access design tokens, create your styles using a function that receives the theme as the first parameter:
 
 ```tsx
+// Example usage
 import { StyleSheet, View, Text } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
@@ -107,13 +103,12 @@ const styles = StyleSheet.create(theme => ({
 }));
 ```
 
-### Available Design Tokens
-
 #### Colors
 
 The theme provides a comprehensive color palette organized by semantic meaning:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   // Primary colors
   primaryButton: {
@@ -147,6 +142,7 @@ const styles = StyleSheet.create(theme => ({
 Use consistent spacing values from the design system:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     // Use space tokens for consistent spacing
@@ -171,6 +167,7 @@ const styles = StyleSheet.create(theme => ({
 Access font families, sizes, weights, and line heights:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   heading: {
     fontFamily: theme.font.family.display, // Comic Hams
@@ -198,6 +195,7 @@ const styles = StyleSheet.create(theme => ({
 Use consistent border radius values:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   card: {
     borderRadius: theme.borderRadius.lg,
@@ -218,6 +216,7 @@ const styles = StyleSheet.create(theme => ({
 Apply consistent shadow styles:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   card: {
     ...theme.shadow.md,
@@ -236,6 +235,7 @@ const styles = StyleSheet.create(theme => ({
 Create responsive layouts using the built-in breakpoint system:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     padding: {
@@ -265,6 +265,7 @@ const styles = StyleSheet.create(theme => ({
 Styles automatically adapt to the current color mode when using theme tokens:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     // Automatically switches between light and dark mode
@@ -284,6 +285,7 @@ const styles = StyleSheet.create(theme => ({
 You can also define styles that apply only in light or dark mode:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   text: {
     color: theme.isLight ? theme.color.grey[900] : theme.color.grey[100],
@@ -296,6 +298,7 @@ const styles = StyleSheet.create(theme => ({
 Access theme values and device information at runtime:
 
 ```tsx
+// Example usage
 import { StyleSheet, UnistylesRuntime } from '@utilitywarehouse/hearth-react-native';
 
 const styles = StyleSheet.create((theme, rt) => ({
@@ -323,6 +326,7 @@ Read more about the [Unistyles Runtime API](https://www.unistyl.es/v3/references
 Use component-specific design tokens for consistent styling:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   button: {
     backgroundColor: theme.components.button.background.primary,
@@ -351,6 +355,7 @@ Unistyles provides powerful variant systems that allow you to create flexible, r
 Variants allow you to define different styles based on props passed to your component:
 
 ```tsx
+// Example usage
 import { StyleSheet, View, Text } from '@utilitywarehouse/hearth-react-native';
 
 interface ButtonProps {
@@ -449,6 +454,7 @@ const styles = StyleSheet.create(theme => ({
 You can also use boolean values for simpler variant logic:
 
 ```tsx
+// Example usage
 interface AlertProps {
   message: string;
   isError?: boolean;
@@ -523,6 +529,7 @@ Read more about [Unistyles Variants](https://www.unistyl.es/v3/references/varian
 Compound variants allow you to apply specific styles when certain combinations of variants are active:
 
 ```tsx
+// Example usage
 interface BadgeProps {
   variant?: 'solid' | 'outline' | 'soft';
   color?: 'purple' | 'green' | 'red' | 'grey';
@@ -742,6 +749,7 @@ Read more about [Unistyles Compound Variants](https://www.unistyl.es/v3/referenc
 You can specify default variants that will be applied when no variant is explicitly set:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   button: {
     borderRadius: theme.borderRadius.md,
@@ -777,6 +785,7 @@ Read more about [Unistyles Default Variants](https://www.unistyl.es/v3/reference
 You can combine variants with responsive breakpoints:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   card: {
     borderRadius: theme.borderRadius.lg,
@@ -809,11 +818,10 @@ const styles = StyleSheet.create(theme => ({
 
 Using variants and compound variants with Hearth React Native allows you to build flexible, maintainable component APIs that adapt to different use cases while maintaining consistency with your design system.
 
-## Best Practices
-
 ### 1. Always Use Theme Tokens
 
 ```tsx
+// Example usage
 // ✅ Good - Uses theme tokens
 const styles = StyleSheet.create(theme => ({
   text: {
@@ -834,6 +842,7 @@ const styles = StyleSheet.create({
 ### 2. Leverage Responsive Design
 
 ```tsx
+// Example usage
 // ✅ Good - Responsive design
 const styles = StyleSheet.create(theme => ({
   container: {
@@ -849,6 +858,7 @@ const styles = StyleSheet.create(theme => ({
 ### 3. Use Semantic Color Names
 
 ```tsx
+// Example usage
 // ✅ Good - Semantic meaning
 const styles = StyleSheet.create(theme => ({
   errorText: {
@@ -863,6 +873,7 @@ const styles = StyleSheet.create(theme => ({
 ### 4. Consistent Spacing
 
 ```tsx
+// Example usage
 // ✅ Good - Consistent spacing scale
 const styles = StyleSheet.create(theme => ({
   card: {
@@ -874,10 +885,3 @@ const styles = StyleSheet.create(theme => ({
 ```
 
 By following these patterns and using the design tokens provided by Hearth React Native, you'll create consistent, maintainable, and accessible user interfaces that work seamlessly across different platforms and screen sizes.
-
-<NextPrevPage
-  prevLink="changelog"
-  prevTitle="Changelog"
-  nextLink="theme-tokens"
-  nextTitle="Theme Tokens"
-/>

package/{docs/theme-tokens.mdx → public/llms/docs/theme-tokens.md}

@@ -1,11 +1,3 @@
-import { ColorItem, ColorPalette, Meta } from '@storybook/addon-docs/blocks';
-import { color } from '@utilitywarehouse/hearth-tokens/js';
-import { Box, Link } from '../src/components';
-import { BackToTopButton, NextPrevPage } from './components';
-
-<Meta title="Theme Tokens" />
-<BackToTopButton />
-
 # Theme Tokens
 
 Hearth React Native provides a comprehensive set of design tokens that ensure consistency across your application. These tokens are built on top of the primitive design system and include semantic meanings for colors, typography, spacing, and other design properties.
@@ -40,6 +32,7 @@ Theme tokens are accessible through the theme object in your stylesheets or with
 Here's an example of how to use them in a component:
 
 ```tsx
+// Example usage
 import { StyleSheet, View, Text } from '@utilitywarehouse/hearth-react-native';
 
 const MyComponent = () => {
@@ -95,6 +88,7 @@ Utility tokens are tokens provide helpful context or helper functions to simplif
 They can be used to create consistent styles across your application.
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     backgroundColor: theme.isDark ? theme.color.grey[900] : theme.color.grey[100],
@@ -119,7 +113,7 @@ The color system provides both semantic and primitive color tokens that automati
 You can view the full color scales below.
 
 <Box
-  style={{
+style={{
     position: 'sticky',
     top: 0,
     width: 240,
@@ -129,7 +123,9 @@ You can view the full color scales below.
     marginLeft: '-260px !important',
     zIndex: 1,
   }}
+
 >
+
   <ul
     style={{
       listStyleType: 'none',
@@ -168,6 +164,7 @@ You can view the full color scales below.
 These colors represent the core brand identity and various services:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   brandButton: {
     backgroundColor: theme.color.surface.brand.default,
@@ -207,6 +204,7 @@ Semantic colors provide meaning and context to your UI elements:
 #### Background Colors
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   primaryBackground: {
     backgroundColor: theme.color.background.primary, // Main app background
@@ -223,6 +221,7 @@ const styles = StyleSheet.create(theme => ({
 #### Text Colors
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   primaryText: {
     color: theme.color.text.primary, // Main text color
@@ -239,6 +238,7 @@ const styles = StyleSheet.create(theme => ({
 #### Interactive Colors
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   primaryButton: {
     backgroundColor: theme.color.interactive.brand.surface.strong.default,
@@ -266,6 +266,7 @@ const styles = StyleSheet.create(theme => ({
 #### Feedback Colors
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   errorMessage: {
     backgroundColor: theme.color.feedback.danger.surface.subtle,
@@ -590,6 +591,7 @@ const styles = StyleSheet.create(theme => ({
 Access the full primitive color palette for custom use cases:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   customElement: {
     backgroundColor: theme.color.purple[400],
@@ -661,6 +663,7 @@ The typography system provides a cohesive set of font properties based on the de
 ### Font Family
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   heading: {
     fontFamily: theme.font.family.heading, // Comic Hams
@@ -685,6 +688,7 @@ Available font families:
 The font size scale provides consistent typography sizing:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   caption: {
     fontSize: theme.font.size['50'], // 10px
@@ -726,6 +730,7 @@ Available font sizes:
 ### Font Weight
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   regular: {
     fontWeight: theme.font.weight.regular, // 400
@@ -747,6 +752,7 @@ const styles = StyleSheet.create(theme => ({
 Optimized letter spacing values for each font size:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   tightText: {
     letterSpacing: theme.letterSpacing['700'], // Tight spacing for large text
@@ -762,6 +768,7 @@ const styles = StyleSheet.create(theme => ({
 Consistent line height values for optimal readability:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   bodyText: {
     lineHeight: theme.lineHeight['400'], // 22px for body text
@@ -777,6 +784,7 @@ const styles = StyleSheet.create(theme => ({
 The spacing system provides a consistent scale for padding, margins, and gaps:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     padding: theme.space['200'], // 16px
@@ -834,6 +842,7 @@ These responsive layout spacings live under `theme.layout.[mobile|tablet|desktop
 layout structure (page/frame scaffolding) rather than component-level internal spacing (which should prefer the core `space` scale).
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   pageSection: {
     padding: theme.space.xl, // 20px on mobile, 24px on tablet/desktop
@@ -862,11 +871,10 @@ Percentage-based spacing is also available:
 - `1/5`, `2/5`, `3/5`, `4/5`
 - `1/6`, `5/6`, `full` (100%)
 
-## Border
-
 ### Border Width
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   thinBorder: {
     borderWidth: theme.borderWidth['1'], // 1px
@@ -880,6 +888,7 @@ const styles = StyleSheet.create(theme => ({
 ### Border Radius
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   card: {
     borderRadius: theme.borderRadius.lg, // 12px
@@ -909,6 +918,7 @@ Available border radius values:
 The shadow system provides elevation through predefined shadow styles:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   card: {
     ...theme.shadow.sm, // Subtle shadow
@@ -927,6 +937,7 @@ const styles = StyleSheet.create(theme => ({
 Access responsive layout values for different screen sizes:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   container: {
     padding: {
@@ -943,6 +954,7 @@ const styles = StyleSheet.create(theme => ({
 Access component-specific design tokens for consistent styling:
 
 ```tsx
+// Example usage
 const styles = StyleSheet.create(theme => ({
   customButton: {
     backgroundColor: theme.components.button.background.primary,
@@ -965,10 +977,3 @@ We also offer a dedicated tokens package that provides access to all design toke
 This package can be used independently or alongside the main Hearth React Native library.
 
 To read more about the tokens package, visit the [Hearth Tokens documentation](https://hearth.prod.uw.systems/?path=/docs/tokens_introduction--docs).
-
-<NextPrevPage
-  prevLink="/?path=/docs/styling--docs"
-  prevTitle="Styling"
-  nextLink="/?path=/docs/hooks--docs"
-  nextTitle="Hooks"
-/>

package/public/llms.txt

@@ -0,0 +1,123 @@
+# Hearth React Native
+
+> @utilitywarehouse/hearth-react-native - React Native component library for Utility Warehouse products.
+
+## Guides
+
+- [Adding Shadows](llms/docs/adding-shadows.md)
+  - Using Predefined Shadows
+  - Components with Shadow Props
+- [All Components](llms/docs/all-components.md)
+- [Dark Mode Best Practice](llms/docs/dark-mode-best-practice.md)
+  - Setting Up Dark Mode
+  - Use Semantic Theme Colours
+  - Use Semantic Utility Props
+  - Use the asset libraries
+  - `ThemedImage` component
+- [Getting Started](llms/docs/getting-started.md)
+- [Hooks](llms/docs/hooks.md)
+  - useTheme
+  - useToken
+  - useColorMode
+  - useBreakpointValue
+  - useMedia
+- [Hearth React Native](llms/docs/introduction.md)
+  - Installation
+  - Additional packages
+  - Fonts
+  - Babel configuration
+  - Jest configuration
+- [Layout Components](llms/docs/layout-components.md)
+  - Box
+  - Container
+  - Flex
+  - Grid
+- [Styling](llms/docs/styling.md)
+  - Unistyles Features
+  - Usage
+  - Design Tokens and Theme
+  - Responsive Design with Breakpoints
+  - Dark Mode Support
+  - Color Mode Specific Styles
+  - Runtime Access
+  - Component-Specific Tokens
+  - Variants and Compound Variants
+- [Theme Tokens](llms/docs/theme-tokens.md)
+  - How to Use Tokens
+  - Utility Tokens
+  - Colors
+  - Typography
+  - Spacing
+  - Shadows
+  - Layout Tokens
+  - Component Tokens
+  - Tokens Package
+
+## Components
+
+- [Accordion](llms/components/accordion.md): The Accordion component is a vertically stacked set of interactive headers that each reveal a section of content.
+- [Alert](llms/components/alert.md): The `Alert` component displays a short, important message in a way that attracts the user's attention without interrupting the user's task.
+- [Avatar](llms/components/avatar.md): Avatars help humanise the product experience by connecting users with the product and to each other.
+- [Badge](llms/components/badge.md): Use the `Badge` component to draw attention to another interface element or to provide additional context (such as status).
+- [Banner](llms/components/banner.md): The `Banner` component is a versatile card-based component for displaying informational content with an icon or image. It supports various layouts, interactive features like pressable states and close buttons, and optional action elements like buttons or links.
+- [BodyText](llms/components/body-text.md): The `BodyText` component gives you the ability to create text for your screen. It can be used to display text in different sizes and styles.
+- [Bottom Sheet](llms/components/bottom-sheet.md): The `BottomSheet` component provides a drawer-like interface that slides up from the bottom of the screen. It's commonly used for displaying additional content or actions without navigating away from the current screen.
+- [Box](llms/components/box.md): When you need to center-align content, the Center component comes in handy. It is a layout component that can be used with other components to create complex layouts and positioning.
+- [Button](llms/components/button.md): The `Button` component is used to trigger an action or event, such as submitting a form, opening a dialog, canceling an action, or performing a delete operation.
+- [Card](llms/components/card.md): A Card component serves as a visual container that groups related content and actions.
+- [Carousel](llms/components/carousel.md): Carousels provide users with a dynamic and interactive way to browse through a series of content items, such as images, articles, or products. It allows users to view multiple items within a confined space, enabling efficient content discovery and engagement.
+- [Center](llms/components/center.md): When you need to center-align content, the Center component comes in handy. It is a layout component that can be used with other components to create complex layouts and positioning.
+- [Checkbox](llms/components/checkbox.md): Whether you're building a simple form or a complex data collection system, the Checkbox component offers a user-friendly way for users to select multiple options from a list.
+- [Combobox](llms/components/combobox.md): The `Combobox` component lets people search and select from a list inside a bottom sheet. It keeps the trigger text and the bottom sheet search input in sync, and can render either the built-in options list or fully custom sheet content.
+- [Container](llms/components/container.md): The Container component is a layout primitive that provides consistent spacing and structure using the design system's layout tokens. It automatically applies responsive margin and padding based on the current breakpoint, and supports additional customization through spacing props.
+- [Currency Input](llms/components/currency-input.md): An input specialised for monetary amounts. It shows a currency symbol prefix and uses a decimal keypad where supported.
+- [Date Input](llms/components/date-input.md): The `DateInput` component allows users to enter dates manually using separate input fields for day, month, and year. It provides flexibility to show only the date segments you need, supports validation states, and integrates seamlessly with the React Native form system.
+- [Date Picker](llms/components/date-picker.md): The `DatePicker` component presents a calendar experience in a bottom sheet so people can choose one or more dates without leaving the current screen. It supports single-day, ranged, and multi-date selection while respecting locale, calendar, and availability rules.
+- [Date Picker Input](llms/components/date-picker-input.md): `DatePickerInput` extends the base input to present a calendar trigger for choosing dates while still allowing direct text entry. It keeps the field inline while delegating selection to the `DatePicker` bottom sheet and formats values with Day.js when needed. The default `DD/MM/YYYY` mask auto-inserts separators and surfaces a numeric keypad for faster entry.
+- [Description List](llms/components/description-list.md): Display pairs of related metadata (heading + description). Supports column (stacked) and row (two-column) layouts, optional SectionHeader (heading + helper text), and per-item action links.
+- [DetailText](llms/components/detail-text.md): The `DetailText` component gives you the ability to create text for your screen. It can be used to display detail text in different sizes and styles.
+- [Divider](llms/components/divider.md): `Divider` components in `hearth-react-native` enhances visual organisation by creating clear boundaries between sections, improving readability and content grouping. They reinforce the visual hierarchy, making it easier for users to understand relationships between elements.
+- [Expandable](llms/components/expandable.md): The Expandable component is a primitive for creating expandable content with smooth animations. It's commonly used as a building block for components like accordions, collapsible sections, and other interactive content that needs to expand and collapse.
+- [Expandable Card](llms/components/expandable-card.md): The `ExpandableCard` component is an interactive card that expands to reveal additional content when clicked. It's a Card component with smooth expansion animations, making it perfect for displaying collapsible information sections.
+- [Flex](llms/components/flex.md): When you need to center-align content, the Center component comes in handy. It is a layout component that can be used with other components to create complex layouts and positioning.
+- [Form Field](llms/components/form-field.md): The `FormField` component is a container for form elements such as input fields. It provides a consistent layout and styling for form elements in which developers can provide important context to form elements. This context can include whether the element is invalid, disabled, or required.
+- [Grid](llms/components/grid.md): The Grid component helps you create responsive grid layouts with configurable columns and spacing. It's perfect for creating photo galleries, card layouts, and other grid-based UI elements.
+- [Heading](llms/components/heading.md): The `Heading` component gives you the ability to create headings for your screen with different sizes.
+- [Highlight Banner](llms/components/highlight-banner.md): A `HighlightBanner` component is a specialised card layout designed for highlighting featured content with an image. It combines a colored heading banner, an optional image, and descriptive text with optional action buttons or links. Perfect for promotional content, featured articles, or important announcements.
+- [Icon Button](llms/components/icon-button.md): The `IconButton` component is used to trigger an action or event, such as opening a dialog, canceling an action, or performing a delete operation.
+- [Icon Container](llms/components/icon-container.md): The `IconContainer` component provides a consistent background and sizing (via component tokens) for any standalone icon, with semantic colour families and subtle/emphasis variants.
+- [Icons](llms/components/icon.md): Icons are often used to enhance the usability and accessibility of digital products by providing users with clear and intuitive visual cues. It serves as an intuitive and easily recognizable way to communicate with users.
+- [Indicator Icon Button](llms/components/indicator-icon-button.md): The `IndicatorIconButton` component is used to trigger an action or event, such as opening a dialog or navigating to other screen. It extends the regular `UnstyledIconButton` with an optional red dot indicator in the top-right corner, useful for showing notifications or unread status.
+- [Inline Link](llms/components/inline-link.md): An `InlineLink` is a hyperlink embedded directly within a sentence or paragraph of text.
+- [Input](llms/components/input.md): The input component is a text field that allows users to enter text, numbers, or other data. It is commonly used in forms and search fields.
+- [Link](llms/components/link.md): Links are used to navigate a user to another screen or website, another place on the same page, or to open a link in a new tab.
+- [List](llms/components/list.md): The List component serves as the primary wrapper for List Items and List Heading components.
+- [Menu](llms/components/menu.md): The `Menu` component provides a bottom sheet modal with a list of actions. It's perfect for contextual menus, action sheets, and option lists. The component uses `BottomSheetModal` under the hood and includes `MenuItem` components that can display icons, text, and support different color schemes.
+- [Modal](llms/components/modal.md): The `Modal` component provides a versatile dialog interface that slides up from the bottom of the screen. It's built on top of
+- [Nav Modal](llms/components/nav-modal.md): The `NavModal` component is the screen-based modal layout for navigation flows. Use it when a screen is already being presented by React Navigation with `presentation: 'modal'` or `presentation: 'fullScreenModal'` and you want Hearth's modal structure, actions, and Android close animation support.
+- [Pagination](llms/components/pagination.md): Pagination helps users move between pages of content while keeping the current position visible. It supports both a full page list and a condensed “Page X of Y” layout.
+- [Pill Group](llms/components/pill-group.md): A container component that groups multiple `Pill` components together for filtering and categorization. It provides layout control with optional wrapping behavior and manages selection state.
+- [Progress Bar](llms/components/progress-bar.md): Progress bars communicate task completion for linear flows and bounded operations. Use the linear variant for
+- [Progress Stepper](llms/components/progress-stepper.md): A form helper component that displays a series of dots connected by lines, showing the progress through a multi-step process. Each step can be marked as completed, active, or uncompleted.
+- [Radio](llms/components/radio.md): The Radio component presents users with predefined choices and enables them to select only one option. It is commonly used for providing a single-choice selection in forms or surveys.
+- [Radio Card](llms/components/radio-card.md): The `RadioCard` component is a UI element that allows users to select one option from a set of predefined choices.
+- [Rating](llms/components/rating.md): Use Rating to collect a score with an optional descriptive label. Supports star and emoji variants.
+- [Roundel](llms/components/roundel.md): The `Roundel` component is a compact status indicator with success, pending, and error variants.
+- [Section Header](llms/components/section-header.md): Use the `Section Header` component to help define and separate content within a screen. It provides structure, clarity, and improves page scannability for users. It is nested within components, such as List, but can be used outside of components too.
+- [Segmented Control](llms/components/segmented-control.md): Segmented Control lets users switch between a small set of related options.
+- [Select](llms/components/select.md): The `Select` component creates a dropdown menu that allows users to choose from a list of options. It's commonly used in forms for selecting one option from many.
+- [Skeleton](llms/components/skeleton.md): The `Skeleton` component is used to show a loading state for a component that is still loading.
+- [Spinner](llms/components/spinner.md): Using a Spinner is a common method for indicating that an asynchronous process is ongoing. Additionally, it informs users that they should refrain from clicking or tapping the UI until the loading state has been resolved.
+- [Stepper Input](llms/components/stepper-input.md): The Stepper Input combines a numeric text input with decrement and increment controls. Use it when the value should stay within a defined range but still needs direct text entry.
+- [Switch](llms/components/switch.md): The Switch component is used to indicate switching between two opposing options. Switches allow users
+- [Table](llms/components/table.md): Table arranges structured data into rows and columns, with optional pagination beneath the rows. The React Native version uses horizontal scrolling automatically when the columns need more space than the viewport allows.
+- [Tabs](llms/components/tabs.md): Tabs are a navigational component that allows users to move easily between groups of related content.
+- [Textarea](llms/components/textarea.md): The input component is a text field that allows users to enter text, numbers, or other data. It is commonly used in forms and search fields.
+- [Themed Image](llms/components/themed-image.md): The `ThemedImage` component automatically switches between light and dark mode images or SVG components based on the current theme. It's perfect for illustrations, logos, or any visual assets that need different appearances for light and dark modes.
+- [Time Picker](llms/components/time-picker.md): `TimePicker` presents a wheel-based time selector inside a bottom sheet, letting people pick hours and minutes without leaving the current context. It supports 12-hour and 24-hour clocks and returns a JavaScript `Date` whenever the selection changes.
+- [Time Picker Input](llms/components/time-picker-input.md): `TimePickerInput` extends the base input to present a time picker trigger while still allowing direct text entry. It keeps the field inline and formats values with Day.js when needed.
+- [Timeline](llms/components/timeline.md): Timeline presents a sequence of related stops or steps using either a static stop indicator or a progress state indicator. Each item supports a label, optional helper text, and optional custom content.
+- [Toast](llms/components/toast.md): The `Toast` component provides a non-intrusive way to display brief messages to users. Toasts appear at the bottom of the screen, can be stacked vertically, and automatically dismiss after a configurable duration. They support swipe-to-dismiss gestures and can include icons, action links, and a dismiss button.
+- [Toggle Button Card](llms/components/toggle-button-card.md): The `ToggleButtonCard` component is a UI element that allows users to select one option from a set of predefined choices.
+- [UL & OL (Lists)](llms/components/html-elements/lists.md): The `UL` (Unordered List) and `OL` (Ordered List) components are used to display lists of items. `UL` displays a bulleted list, and `OL` displays a numbered list. The `LI` (List Item) component is used to define each item within these lists.
+- [Verification Input](llms/components/verification-input.md): The verification input component is used to capture OTP (One Time Password) or other verification codes.

package/scripts/init-ai.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * init-ai.js
+ * Adds the @utilitywarehouse/hearth-react-native AI skill reference to the
+ * project's AI assistant config file.
+ *
+ * Usage: npx @utilitywarehouse/hearth-react-native init-ai
+ */
+
+import fs from 'fs';
+import path from 'path';
+import readline from 'readline';
+const PACKAGE_NAME = '@utilitywarehouse/hearth-react-native';
+
+function resolveSkillPath(projectRoot) {
+  let dir = projectRoot;
+  while (dir !== path.parse(dir).root) {
+    const candidate = path.join(dir, 'node_modules', PACKAGE_NAME);
+    if (fs.existsSync(candidate)) {
+      return path.relative(projectRoot, path.join(candidate, 'SKILL.md')).replace(/\\/g, '/');
+    }
+    dir = path.dirname(dir);
+  }
+  return `node_modules/${PACKAGE_NAME}/SKILL.md`;
+}
+
+// Config files for each tool, in detection priority order
+function buildAiTools(skillPath) {
+  return [
+    {
+      name: 'Claude Code',
+      files: ['CLAUDE.md'],
+      line: `@${skillPath}`,
+      supportsAtImport: true,
+    },
+    {
+      name: 'Cursor',
+      files: ['.cursorrules'],
+      line: `@${skillPath}`,
+      supportsAtImport: true,
+    },
+    {
+      name: 'Windsurf',
+      files: ['.windsurfrules'],
+      line: `@${skillPath}`,
+      supportsAtImport: true,
+    },
+    {
+      name: 'Cline / Roo',
+      files: ['.clinerules'],
+      line: `@${skillPath}`,
+      supportsAtImport: true,
+    },
+    {
+      name: 'Codex / OpenAI agents',
+      files: ['AGENTS.md'],
+      line: `See ${skillPath} for ${PACKAGE_NAME} component usage guidelines.`,
+      supportsAtImport: false,
+    },
+    {
+      name: 'GitHub Copilot',
+      files: ['.github/copilot-instructions.md'],
+      line: `See ${skillPath} for ${PACKAGE_NAME} component usage guidelines.`,
+      supportsAtImport: false,
+    },
+  ];
+}
+
+const COMMENT = `<!-- ${PACKAGE_NAME} — AI skill for component library usage guidance -->\n<!-- Added by: npx ${PACKAGE_NAME} init-ai -->`;
+
+function findProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function alreadyAdded(content, line) {
+  return content.includes(line.trim());
+}
+
+function appendToFile(filePath, line) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  let content = '';
+  let existed = false;
+  if (fs.existsSync(filePath)) {
+    content = fs.readFileSync(filePath, 'utf8');
+    existed = true;
+  }
+
+  if (alreadyAdded(content, line)) {
+    return { existed, alreadyPresent: true };
+  }
+
+  const separator = content.length > 0 && !content.endsWith('\n') ? '\n' : '';
+  fs.appendFileSync(filePath, `${separator}\n${COMMENT}\n${line}\n`);
+  return { existed, alreadyPresent: false };
+}
+
+function detectAndUpdate(projectRoot) {
+  const results = [];
+  for (const tool of AI_TOOLS) {
+    for (const file of tool.files) {
+      const filePath = path.join(projectRoot, file);
+      if (fs.existsSync(filePath)) {
+        const { alreadyPresent } = appendToFile(filePath, tool.line);
+        results.push({ tool: tool.name, file, alreadyPresent, created: false });
+      }
+    }
+  }
+  return results;
+}
+
+function promptCreate(projectRoot, aiTools) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question('\nNo AI assistant config file detected. Create CLAUDE.md? (Y/n) ', answer => {
+    rl.close();
+    if (answer.trim().toLowerCase() !== 'n') {
+      const tool = aiTools.find(t => t.name === 'Claude Code');
+      const filePath = path.join(projectRoot, 'CLAUDE.md');
+      appendToFile(filePath, tool.line);
+      console.log(`\n✅  Created CLAUDE.md with ${PACKAGE_NAME} skill reference.`);
+    } else {
+      console.log('\nSkipped. You can add the skill manually — see the README for instructions.');
+    }
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const projectRoot = findProjectRoot();
+const skillPath = resolveSkillPath(projectRoot);
+const AI_TOOLS = buildAiTools(skillPath);
+
+console.log(`\n🔍  Scanning for AI assistant config files in ${projectRoot}...\n`);
+
+const results = detectAndUpdate(projectRoot);
+
+if (results.length === 0) {
+  promptCreate(projectRoot, AI_TOOLS);
+} else {
+  for (const r of results) {
+    if (r.alreadyPresent) {
+      console.log(`⏭   ${r.tool} (${r.file}) — skill already present, skipped`);
+    } else {
+      console.log(`✅  ${r.tool} (${r.file}) — skill reference added`);
+    }
+  }
+  console.log(`\nDone! Your AI assistant will now use the ${PACKAGE_NAME} skill.\n`);
+}