@utilitywarehouse/hearth-react-native 0.1.0

package/docs/theme-tokens.mdx

@@ -0,0 +1,524 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+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.
+
+- [How to Use Tokens](#how-to-use-tokens)
+- [Utility Tokens](#utility-tokens)
+- [Colors](#colors)
+  - [Brand and Service Colors](#brand-and-service-colors)
+  - [Semantic Colors](#semantic-colors)
+  - [Primitive Color Palette](#primitive-color-palette)
+- [Typography](#typography)
+  - [Font Family](#font-family)
+  - [Font Size](#font-size)
+  - [Font Weight](#font-weight)
+  - [Letter Spacing](#letter-spacing)
+  - [Line Height](#line-height)
+- [Spacing](#spacing)
+- [Border](#border)
+  - [Border Width](#border-width)
+  - [Border Radius](#border-radius)
+- [Shadows](#shadows)
+- [Layout Tokens](#layout-tokens)
+- [Component Tokens](#component-tokens)
+- [Tokens Package](#tokens-package)
+
+## How to Use Tokens
+
+Theme tokens are accessible through the theme object in your stylesheets or with the `useTheme` hook.
+Here's an example of how to use them in a component:
+
+```tsx
+import { StyleSheet, View, Text } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Hello, Hearth!</Text>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    backgroundColor: theme.color.background.primary,
+    padding: theme.space[4],
+    borderRadius: theme.borderRadius.lg,
+    borderColor: theme.color.border.subtle.color,
+    borderWidth: theme.borderWidth[1],
+  },
+  title: {
+    color: theme.color.text.primary,
+    fontSize: theme.font.size[300],
+    fontFamily: theme.font.family.heading,
+    fontWeight: theme.font.weight.bold,
+  },
+}));
+
+// or using the `useTheme` hook:
+import { useTheme } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const theme = useTheme();
+
+  return (
+    <View style={{ backgroundColor: theme.color.background.primary, padding: theme.space[4] }}>
+      <Text
+        style={{
+          color: theme.color.text.primary,
+          fontSize: theme.font.size[300],
+          fontFamily: theme.font.family.heading,
+          fontWeight: theme.font.weight.bold,
+        }}
+      >
+        Hello, Hearth!
+      </Text>
+    </View>
+  );
+};
+```
+
+## Utility Tokens
+
+Utility tokens are tokens provide helpful context or helper functions to simplify styling.
+They can be used to create consistent styles across your application.
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  container: {
+    backgroundColor: theme.isDark ? theme.color.grey[900] : theme.color.grey[100],
+    borderColor: theme.colorMode === 'light' ? theme.color.grey[300] : theme.color.grey[700],
+    padding: theme.space[200],
+    margin: theme.space[2],
+    borderRadius: theme.borderRadius.md,
+  },
+}));
+```
+
+| Token       | Description                                      |
+| ----------- | ------------------------------------------------ |
+| `isDark`    | Boolean indicating if the current theme is dark  |
+| `isLight`   | Boolean indicating if the current theme is light |
+| `colorMode` | Current color mode, either 'light' or 'dark'     |
+
+## Colors
+
+The color system provides both semantic and primitive color tokens that automatically adapt to light and dark themes.
+
+You can view the full color palette in the [Hearth Tokens documentation](https://hearth.prod.uw.systems/?path=/docs/tokens_colours--docs#available-colour-tokens).
+
+### Brand and Service Colors
+
+These colors represent the core brand identity and various services:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  brandButton: {
+    backgroundColor: theme.color.surface.brand.default.color,
+    borderColor: theme.components.button.border.primary,
+  },
+  energyCard: {
+    backgroundColor: theme.color.surface.energy.default.color,
+    color: theme.color.text.inverted,
+  },
+  broadbandAccent: {
+    backgroundColor: theme.color.surface.broadband.subtle.color,
+  },
+}));
+```
+
+Available brand and service colors:
+
+- **Brand**: `purple` - Primary brand color
+- **Energy**: `energyBlue` - Energy service
+- **Broadband**: `broadbandGreen` - Broadband service
+- **Mobile**: `mobileRose` - Mobile service
+- **Insurance**: `insuranceOrange` - Insurance service
+- **Cashback**: `cashbackLilac` - Cashback service
+- **Pig**: `piggyPink` - Savings/Piggy service
+
+### Semantic Colors
+
+Semantic colors provide meaning and context to your UI elements:
+
+#### Background Colors
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  primaryBackground: {
+    backgroundColor: theme.color.background.primary, // Main app background
+  },
+  secondaryBackground: {
+    backgroundColor: theme.color.background.secondary, // Card/modal backgrounds
+  },
+  brandBackground: {
+    backgroundColor: theme.color.background.brand, // Brand-colored backgrounds
+  },
+}));
+```
+
+#### Text Colors
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  primaryText: {
+    color: theme.color.text.primary, // Main text color
+  },
+  secondaryText: {
+    color: theme.color.text.secondary, // Subtle/muted text
+  },
+  invertedText: {
+    color: theme.color.text.inverted, // Text on dark backgrounds
+  },
+}));
+```
+
+#### Interactive Colors
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  primaryButton: {
+    backgroundColor: theme.color.interactive.brand.surface.strong.defaultColor,
+    color: theme.color.interactive.brand.foreground.strong.color,
+  },
+  destructiveButton: {
+    backgroundColor: theme.color.interactive.destructive.surface.strong.defaultColor,
+    color: theme.color.interactive.destructive.foreground.strong.color,
+  },
+  affirmativeButton: {
+    backgroundColor: theme.color.interactive.affirmative.surface.strong.defaultColor,
+    color: theme.color.interactive.affirmative.foreground.strong.color,
+  },
+}));
+```
+
+#### Feedback Colors
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  errorMessage: {
+    backgroundColor: theme.color.feedback.danger.subtle.color,
+    color: theme.color.feedback.danger.default.color,
+    borderColor: theme.color.feedback.danger.default.color,
+  },
+  successMessage: {
+    backgroundColor: theme.color.feedback.positive.subtle.color,
+    color: theme.color.feedback.positive.default.color,
+  },
+  warningMessage: {
+    backgroundColor: theme.color.feedback.warning.subtle.color,
+    color: theme.color.feedback.warning.default.color,
+  },
+  infoMessage: {
+    backgroundColor: theme.color.feedback.info.subtle.color,
+    color: theme.color.feedback.info.default.color,
+  },
+}));
+```
+
+### Primitive Color Palette
+
+Access the full primitive color palette for custom use cases:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  customElement: {
+    backgroundColor: theme.color.purple[500],
+    borderColor: theme.color.grey[300],
+    color: theme.color.grey[900],
+  },
+}));
+```
+
+Available primitive colors with full scales (0-1000):
+
+- `blue`, `green`, `red`, `orange`, `yellow`
+- `purple`, `grey`, `warmWhite`
+- `broadbandGreen`, `energyBlue`, `mobileRose`
+- `insuranceOrange`, `cashbackLilac`, `piggyPink`
+
+## Typography
+
+The typography system provides a cohesive set of font properties based on the design system.
+
+### Font Family
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  heading: {
+    fontFamily: theme.font.family.heading, // Comic Hams
+  },
+  bodyText: {
+    fontFamily: theme.font.family.body, // DM Sans
+  },
+  codeText: {
+    fontFamily: theme.font.family.detail, // DM Mono
+  },
+}));
+```
+
+Available font families:
+
+- `heading`: Comic Hams (display font)
+- `body`: DM Sans (body text)
+- `detail`: DM Mono (monospace/code)
+
+### Font Size
+
+The font size scale provides consistent typography sizing:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  caption: {
+    fontSize: theme.font.size['50'], // 10px
+  },
+  small: {
+    fontSize: theme.font.size['75'], // 12px
+  },
+  body: {
+    fontSize: theme.font.size['100'], // 16px
+  },
+  heading: {
+    fontSize: theme.font.size['400'], // 30px
+  },
+  display: {
+    fontSize: theme.font.size['700'], // 60px
+  },
+}));
+```
+
+Available font sizes:
+| Token | Value | Usage |
+|-------|-------|-------|
+| `50` | 10px | Captions, fine print |
+| `75` | 12px | Small text, labels |
+| `90` | 14px | Secondary text |
+| `100` | 16px | Body text (base) |
+| `150` | 18px | Large body text |
+| `200` | 20px | Subheadings |
+| `300` | 24px | Small headings |
+| `400` | 30px | Medium headings |
+| `500` | 36px | Large headings |
+| `550` | 40px | Extra large headings |
+| `600` | 48px | Display text |
+| `700` | 60px | Large display |
+| `800` | 72px | Hero text |
+| `900` | 96px | Extra large display |
+| `1000` | 128px | Maximum display |
+
+### Font Weight
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  regular: {
+    fontWeight: theme.font.weight.regular, // 400
+  },
+  medium: {
+    fontWeight: theme.font.weight.medium, // 500
+  },
+  semibold: {
+    fontWeight: theme.font.weight.semibold, // 600
+  },
+  bold: {
+    fontWeight: theme.font.weight.bold, // 700
+  },
+  heavy: {
+    fontWeight: theme.font.weight.heavy, // 900
+  },
+}));
+```
+
+### Letter Spacing
+
+Optimized letter spacing values for each font size:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  tightText: {
+    letterSpacing: theme.letterSpacing['700'], // Tight spacing for large text
+  },
+  normalText: {
+    letterSpacing: theme.letterSpacing['100'], // Normal spacing for body text
+  },
+}));
+```
+
+### Line Height
+
+Consistent line height values for optimal readability:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  bodyText: {
+    lineHeight: theme.lineHeight['400'], // 22px for body text
+  },
+  headingText: {
+    lineHeight: theme.lineHeight['700'], // 32px for headings
+  },
+}));
+```
+
+## Spacing
+
+The spacing system provides a consistent scale for padding, margins, and gaps:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  container: {
+    padding: theme.space['200'], // 16px
+    margin: theme.space['150'], // 12px
+    gap: theme.space['100'], // 8px
+  },
+  tightSpacing: {
+    padding: theme.space['50'], // 4px
+  },
+  looseSpacing: {
+    padding: theme.space['500'], // 40px
+  },
+}));
+```
+
+Available spacing values:
+| Token | Value | Usage |
+|-------|-------|-------|
+| `0` | 0px | No spacing |
+| `25` | 2px | Minimal spacing |
+| `50` | 4px | Tight spacing |
+| `75` | 6px | Small spacing |
+| `100` | 8px | Base spacing unit |
+| `150` | 12px | Small-medium spacing |
+| `175` | 14px | Compact spacing |
+| `200` | 16px | Standard spacing |
+| `250` | 20px | Medium spacing |
+| `300` | 24px | Large spacing |
+| `350` | 28px | Large spacing |
+| `400` | 32px | Extra large spacing |
+| `500` | 40px | Section spacing |
+| `600` | 48px | Large section spacing |
+| `700` | 56px | Extra large sections |
+| `800` | 64px | Major spacing |
+| `900` | 72px | Maximum spacing |
+| `1000` | 80px | Hero spacing |
+
+Percentage-based spacing is also available:
+
+- `1/2`, `1/3`, `2/3`, `1/4`, `3/4`
+- `1/5`, `2/5`, `3/5`, `4/5`
+- `1/6`, `5/6`, `full` (100%)
+
+## Border
+
+### Border Width
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  thinBorder: {
+    borderWidth: theme.borderWidth['1'], // 1px
+  },
+  thickBorder: {
+    borderWidth: theme.borderWidth['2'], // 2px
+  },
+}));
+```
+
+### Border Radius
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  card: {
+    borderRadius: theme.borderRadius.lg, // 12px
+  },
+  button: {
+    borderRadius: theme.borderRadius.md, // 8px
+  },
+  pill: {
+    borderRadius: theme.borderRadius.full, // 9999px
+  },
+}));
+```
+
+Available border radius values:
+| Token | Value | Usage |
+|-------|-------|-------|
+| `none` | 0px | Sharp corners |
+| `xs` | 4px | Subtle rounding |
+| `sm` | 6px | Small rounding |
+| `md` | 8px | Standard rounding |
+| `lg` | 12px | Large rounding |
+| `xl` | 16px | Extra large rounding |
+| `full` | 9999px | Fully rounded (pills/circles) |
+
+## Shadows
+
+The shadow system provides elevation through predefined shadow styles:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  card: {
+    ...theme.shadow.sm, // Subtle shadow
+  },
+  modal: {
+    ...theme.shadow.lg, // Prominent shadow
+  },
+  floatingButton: {
+    ...theme.shadow.xl, // Strong shadow
+  },
+}));
+```
+
+## Layout Tokens
+
+Access responsive layout values for different screen sizes:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  container: {
+    padding: {
+      base: theme.layout.mobile.spacing.md,
+      md: theme.layout.tablet.spacing.lg,
+      lg: theme.layout.desktop.spacing.xl,
+    },
+  },
+}));
+```
+
+## Component Tokens
+
+Access component-specific design tokens for consistent styling:
+
+```tsx
+const styles = StyleSheet.create(theme => ({
+  customButton: {
+    backgroundColor: theme.components.button.background.primary,
+    borderColor: theme.components.button.border.primary,
+    borderRadius: theme.components.button.borderRadius,
+    paddingHorizontal: theme.components.button.padding.horizontal,
+    paddingVertical: theme.components.button.padding.vertical,
+  },
+  customInput: {
+    backgroundColor: theme.components.input.background.default,
+    borderColor: theme.components.input.border.default,
+    fontSize: theme.components.input.fontSize,
+  },
+}));
+```
+
+## Tokens Package
+
+We also offer a dedicated tokens package that provides access to all design tokens in a structured format.
+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/eslint.config.js

@@ -0,0 +1,30 @@
+// For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
+import storybook from 'eslint-plugin-storybook';
+
+import js from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  { ignores: ['build', 'dist', 'storybook-static'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      '@typescript-eslint/no-explicit-any': 'off',
+    },
+  },
+  storybook.configs['flat/recommended']
+);

package/figma.config.json

@@ -0,0 +1,11 @@
+{
+  "codeConnect": {
+    "include": ["src/**"],
+    "parser": "react",
+    "exclude": [],
+    "label": "React Native",
+    "importPaths": {
+      "packages/react-native/src/*": "@utilitywarehouse/hearth-react-native"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@utilitywarehouse/hearth-react-native",
+  "version": "0.1.0",
+  "description": "Utility Warehouse React Native UI library",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "module": "build/index",
+  "type": "module",
+  "sideEffects": false,
+  "dependencies": {
+    "@expo/html-elements": "latest",
+    "@gluestack-ui/accordion": "1.0.7",
+    "@gluestack-ui/alert": "0.1.15",
+    "@gluestack-ui/button": "1.0.7",
+    "@gluestack-ui/checkbox": "0.1.32",
+    "@gluestack-ui/icon": "0.1.22",
+    "@gluestack-ui/input": "0.1.31",
+    "@gluestack-ui/link": "0.1.22",
+    "@gluestack-ui/pressable": "0.1.16",
+    "@gluestack-ui/radio": "0.1.33",
+    "@gluestack-ui/spinner": "0.1.14",
+    "@gluestack-ui/switch": "0.1.22",
+    "@gluestack-ui/textarea": "0.1.23",
+    "@gorhom/bottom-sheet": "^5.1.6",
+    "@utilitywarehouse/hearth-react-native-icons": "^0.1.0"
+  },
+  "devDependencies": {
+    "@babel/plugin-proposal-export-namespace-from": "^7.18.9",
+    "@chromatic-com/storybook": "^4.0.1",
+    "@figma/code-connect": "^1.3.3",
+    "@storybook/addon-a11y": "^9.0.17",
+    "@storybook/addon-docs": "^9.0.17",
+    "@storybook/addon-vitest": "^9.0.17",
+    "@storybook/react-native-web-vite": "^9.0.17",
+    "@types/react": "^19.1.8",
+    "@vitest/browser": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint-plugin-storybook": "9.0.17",
+    "playwright": "^1.53.1",
+    "react": "^19.1.0",
+    "react-native": "0.80.0",
+    "react-native-edge-to-edge": "1.6.1",
+    "react-native-gesture-handler": "2.26.0",
+    "react-native-nitro-modules": "^0.26.4",
+    "react-native-reanimated": "3.18.0",
+    "react-native-svg": "^15.12.0",
+    "react-native-unistyles": "3.0.7",
+    "react-native-web": "^0.20.0",
+    "remark-gfm": "^4.0.1",
+    "storybook": "^9.0.17",
+    "typescript": "^5.7.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4",
+    "@utilitywarehouse/hearth-fonts": "^0.0.3",
+    "@utilitywarehouse/hearth-react-icons": "^0.1.1",
+    "@utilitywarehouse/hearth-tokens": "^0.0.7"
+  },
+  "peerDependencies": {
+    "react": ">=17 || ^18.0.0 || ^19.0.0",
+    "react-native": ">=0.77",
+    "react-native-gesture-handler": "^2.22.0",
+    "react-native-reanimated": "3.x",
+    "react-native-svg": ">=13.4.0",
+    "react-native-unistyles": ">=>3.0.0",
+    "react-native-web": ">=0.19"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules rm -rf build .turbo",
+    "generateColours": "node ./scripts/generateColours.js",
+    "copyTokens": "node ./scripts/copyTokens.js",
+    "lint:fix": "TIMING=1 eslint --fix --max-warnings 0",
+    "lint": "TIMING=1 eslint --max-warnings 0",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "watch:lab": "tsc --p tsconfig.lab.json  --watch",
+    "figma:create": "figma connect create",
+    "figma:publish": "figma connect publish",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build"
+  }
+}