@utilitywarehouse/hearth-react-native 0.34.5 → 0.35.1

package/{docs/layout-components.docs.mdx → public/llms/docs/layout-components.md}

@@ -1,14 +1,3 @@
-import { ArgTypes, Canvas, Meta } from '@storybook/addon-docs/blocks';
-import StorybookLink from '../../../shared/storybook/StorybookLink';
-import * as BoxStories from '../src/components/Box/Box.stories';
-import * as ContainerStories from '../src/components/Container/Container.stories';
-import * as FlexStories from '../src/components/Flex/Flex.stories';
-import * as GridStories from '../src/components/Grid/Grid.stories';
-import { BackToTopButton, NextPrevPage } from './components';
-
-<Meta title="Layout Components" />
-<BackToTopButton />
-
 # Layout Components
 
 These components focus on creating layouts and can be used as base building
@@ -23,15 +12,21 @@ apply design decisions coherently.
 
 ## Box
 
-<Canvas of={BoxStories.Playground} sourceState="none" />
+```tsx
+// Example usage
+<Box {...args}>
+  <BodyText>{args.children}</BodyText>
+</Box>
+```
 
 `Box` is the most fundamental component, and can be used to provide spacing,
 size and colour to elements. It can be used to control behaviour of child
 elements within `Flex` and `Grid` containers.
 
-You can view the <StorybookLink to="primitives-box">`Box` docs here</StorybookLink>.
+You can view the `Box` docs here.
 
 ```tsx
+// Example usage
 <Box
   padding="400"
   marginBottom="300"
@@ -43,16 +38,32 @@ You can view the <StorybookLink to="primitives-box">`Box` docs here</StorybookLi
 
 ## Container
 
-<Canvas of={ContainerStories.Playground} sourceState="none" />
+```tsx
+// Example usage
+<Box backgroundColor={color.red['100']}>
+  <Container {...args} backgroundColor="secondary">
+    <Box bg={color.blue['400']} p="200" borderRadius="md">
+      <BodyText>Container content 1</BodyText>
+    </Box>
+    <Box bg={color.purple['400']} p="200" borderRadius="md">
+      <BodyText>Container content 2</BodyText>
+    </Box>
+    <Box bg={color.piggyPink['300']} p="200" borderRadius="md">
+      <BodyText>Container content 3</BodyText>
+    </Box>
+  </Container>
+</Box>
+```
 
 `Container` is a specialised layout component that provides consistent page-level
 spacing using the design system's responsive layout tokens. It automatically applies
 appropriate margin and padding based on the current breakpoint, making it ideal for
 wrapping page content or major sections.
 
-You can view the <StorybookLink to="primitives-container">`Container` docs here</StorybookLink>.
+You can view the `Container` docs here.
 
 ```tsx
+// Example usage
 <Container spacing="lg">
   <Box>{...}</Box>
   <Box>{...}</Box>
@@ -63,6 +74,7 @@ When you need custom spacing, you can override the defaults while maintaining
 the convenience of the component:
 
 ```tsx
+// Example usage
 <Container
   marginHorizontal="none"
   spacing="xl"
@@ -73,15 +85,32 @@ the convenience of the component:
 
 ## Flex
 
-<Canvas of={FlexStories.Playground} sourceState="none" />
+```tsx
+// Example usage
+<Flex {...args}>
+  {Array.from({ length: 4 }).map((_, index) => (
+    <Box
+      key={index}
+      // @ts-expect-error - This is a playground
+      bg={`grey${index + 1}00`}
+      w={100 + index * 10}
+      h={100 + index * 10}
+      borderColor="strong"
+      borderWidth="2"
+      borderRadius="md"
+    />
+  ))}
+</Flex>
+```
 
 `Flex` adds a handy set of props for building with flexbox properties. This
 component is useful for defining layouts along an axis, and replaces the `HStack` and `VStack`
 component you may have used in other libraries.
 
-You can view the <StorybookLink to="primitives-flex">`Flex` docs here</StorybookLink>.
+You can view the `Flex` docs here.
 
 ```tsx
+// Example usage
 <Flex
   padding="400"
   spacing="md"
@@ -94,7 +123,17 @@ You can view the <StorybookLink to="primitives-flex">`Flex` docs here</Storybook
 
 ## Grid
 
-<Canvas of={GridStories.Playground} sourceState="none" />
+```tsx
+// Example usage
+<Grid {...args} style={{ width: 400 }}>
+  <GridItem color="#FFD6D6" />
+  <GridItem color="#D6FFD6" />
+  <GridItem color="#D6D6FF" />
+  <GridItem color="#FFFFD6" />
+  <GridItem color="#FFD6FF" />
+  <GridItem color="#D6FFFF" />
+</Grid>
+```
 
 `Grid` is used to create grid layouts, organizing content in columns and rows.
 Like `Flex` and `Box`, the `Grid` component provides access to a range of
@@ -102,19 +141,13 @@ styling props, and to all the properties needed to build a grid layout.
 
 You can easily build responsive layouts using Design System defaults.
 
-You can view the <StorybookLink to="primitives-grid">`Grid` docs here</StorybookLink>.
+You can view the `Grid` docs here.
 
 ```tsx
+// Example usage
 <Grid columns={2} spacing="md">
   <Box>{...}</Box>
   <Box>{...}</Box>
   <Box>{...}</Box>
 </Grid>
 ```
-
-<NextPrevPage
-  prevLink="hooks"
-  prevTitle="Hooks"
-  nextLink="all-components"
-  nextTitle="All Components"
-/>

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"
-/>