@mich8060/chg-design-system 0.1.0

package/.github/workflows/figma-sync.yml

@@ -0,0 +1,30 @@
+name: Figma Sync
+
+on:
+  workflow_dispatch: {}
+  push:
+    branches: [ main ]
+  schedule:
+    - cron: "0 3 * * *" # nightly at 3am UTC
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run pull:figma
+        env:
+          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
+          FIGMA_FILE_ID: ${{ secrets.FIGMA_FILE_ID }}
+      - run: npm run build:tokens
+      - name: Commit & push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add src/scss/ tokens/
+          git commit -m "chore: sync tokens from Figma" || echo "No changes"
+          git push

package/ARCHITECTURE_FIX.md

@@ -0,0 +1,241 @@
+# CSS Token Generator Architecture Fix
+
+## Root Cause Analysis
+
+### Problem 1: Brand Values Injected into Design System Light (`:root`)
+
+**Location**: `generate_structured_css.py` lines 636-648
+
+**Issue**: Non-color variables (buttons, surfaces, borders) get brand override values **hard-coded** directly into `:root`:
+
+```python
+# Lines 636-648: PROBLEMATIC CODE
+if var_id in ds_var_brand_overrides and ds_var_brand_overrides[var_id]:
+    brand_override_value = ds_var_brand_overrides[var_id]['CompHealth']  # Hard-codes CompHealth!
+    css_value = format_value_for_css(brand_override_value, var_type, var_name)
+    scss_parts.append(f"  {css_name}: {css_value};")  # Hard value in :root
+```
+
+**Result**: 
+- `:root` contains `--uds-button-border-primary-default: #009add;` (CompHealth value)
+- `[data-brand="modio"]` tries to override, but both have same specificity
+- Since `:root` comes first, brand blocks can't override it
+
+**Generated CSS (BROKEN)**:
+```css
+:root {
+  --uds-button-border-primary-default: #009add;  /* CompHealth hard-coded! */
+}
+
+[data-brand="modio"] {
+  --uds-button-border-primary-default: #3b82f6;  /* Can't override :root */
+}
+```
+
+### Problem 2: Component Tokens Finalized Too Early
+
+**Location**: `generate_structured_css.py` lines 632-681
+
+**Issue**: Component tokens (buttons, surfaces) are resolved to **hard values** instead of referencing semantic color tokens:
+
+**Current (BROKEN)**:
+```css
+:root {
+  --uds-button-surface-primary-default: #009add;  /* Hard value */
+  --uds-surface-brand-primary: #eae4ee;  /* Hard value */
+}
+```
+
+**Should be**:
+```css
+:root {
+  --uds-button-surface-primary-default: var(--uds-color-primary-500);  /* References semantic token */
+  --uds-surface-brand-primary: var(--uds-color-primary-50);  /* References semantic token */
+}
+```
+
+### Problem 3: Brand Overrides Skipped When Already Injected
+
+**Location**: `generate_structured_css.py` lines 1003-1005
+
+**Issue**: Brand overrides are skipped if they were already injected into Design System:
+
+```python
+# Lines 1003-1005: PROBLEMATIC CODE
+if ds_var_id in ds_var_brand_overrides and brand_name in ds_var_brand_overrides[ds_var_id]:
+    # This variable was already updated in the Design System section, skip adding to brand overrides
+    continue  # Prevents brand blocks from overriding!
+```
+
+**Result**: Brand blocks are empty because variables were already "handled" in `:root`.
+
+### Problem 4: Same Specificity, Order-Dependent Cascade
+
+**Issue**: Both `:root` and `[data-brand="X"]` have the same specificity. The generator writes:
+1. `:root` (with hard-coded brand values)
+2. `[data-brand="X"]` (trying to override)
+
+Since they have same specificity, the **last one wins**. But if `:root` has hard values and brand blocks come later, they should win - but they're being skipped due to Problem 3.
+
+## Required Fixes
+
+### Fix 1: Remove Brand Injection from Design System Light
+
+**Location**: `generate_structured_css.py` lines 632-681
+
+**Change**: Remove the brand override injection logic. Design System Light should **always** use Design System values, never brand values.
+
+**Before**:
+```python
+else:
+    # Non-color variables get their values directly
+    # Check if there's a brand override for this variable - if so, use the first brand's override value
+    if var_id in ds_var_brand_overrides and ds_var_brand_overrides[var_id]:
+        brand_override_value = ds_var_brand_overrides[var_id]['CompHealth']
+        css_value = format_value_for_css(brand_override_value, var_type, var_name)
+        scss_parts.append(f"  {css_name}: {css_value};")  # ❌ REMOVE THIS
+```
+
+**After**:
+```python
+else:
+    # Non-color variables get their values directly from Design System
+    # NEVER inject brand values here - they belong in [data-brand] blocks
+    if light_mode_id:
+        value = resolve_value_for_mode(var_id, light_mode_id, fallback_to_first_mode=True)
+        css_value = format_value_for_css(value, var_type, var_name)
+        if css_value:
+            scss_parts.append(f"  {css_name}: {css_value};")
+```
+
+### Fix 2: Ensure Component Tokens Reference Semantic Tokens
+
+**Location**: `generate_structured_css.py` lines 632-681
+
+**Change**: For component tokens that depend on colors, check if they should reference semantic color tokens instead of hard values.
+
+**Note**: This may require analyzing the variable name to determine if it's a derived token. For now, the immediate fix is to remove brand injection. Component tokens should reference `--uds-color-*` tokens when they represent color-derived values.
+
+**Example**:
+- `uds/button/surface/primary/default` should reference `var(--uds-color-primary-500)` if it's color-derived
+- This requires understanding the token structure from Figma
+
+**For now**: Removing brand injection (Fix 1) will ensure brand blocks can override properly.
+
+### Fix 3: Remove Skip Logic for Brand Overrides
+
+**Location**: `generate_structured_css.py` lines 1003-1005
+
+**Change**: Remove the logic that skips brand overrides if they were already in Design System.
+
+**Before**:
+```python
+if ds_var_id in ds_var_brand_overrides and brand_name in ds_var_brand_overrides[ds_var_id]:
+    # This variable was already updated in the Design System section, skip adding to brand overrides
+    continue  # ❌ REMOVE THIS
+```
+
+**After**:
+```python
+# Always include brand overrides in brand blocks
+# Design System Light no longer injects brand values, so brand blocks must contain all overrides
+```
+
+### Fix 4: Update Filtering Logic
+
+**Location**: `generate_structured_css.py` lines 1045-1069
+
+**Change**: Update the filtering logic to not exclude variables that were in `ds_var_brand_overrides`, since we're no longer injecting them into Design System.
+
+**Before**:
+```python
+# Check if this DS variable was updated in the Design System section
+if ds_var_id in ds_var_brand_overrides and brand_name in ds_var_brand_overrides[ds_var_id]:
+    should_exclude = True  # ❌ This logic is now wrong
+```
+
+**After**:
+```python
+# Since Design System Light no longer injects brand values,
+# we don't need to exclude variables that were in ds_var_brand_overrides
+# Brand blocks should contain all brand-specific overrides
+```
+
+## Implementation Checklist
+
+- [ ] **Fix 1**: Remove brand injection logic (lines 636-648)
+- [ ] **Fix 2**: Ensure Design System Light always uses Design System values (lines 632-681)
+- [ ] **Fix 3**: Remove skip logic for brand overrides (lines 1003-1005)
+- [ ] **Fix 4**: Update filtering logic to not exclude based on `ds_var_brand_overrides` (lines 1045-1069)
+- [ ] **Fix 5**: Remove or repurpose `ds_var_brand_overrides` tracking (it's no longer needed for injection)
+
+## Expected Output After Fix
+
+### Design System Light (`:root`)
+```css
+:root {
+  /* Brand Color Variables (Defaults) */
+  --brand-color-primary-500: #009add;  /* Design System default */
+  
+  /* UDS Color Variables */
+  --uds-color-primary-500: var(--brand-color-primary-500);
+  
+  /* Component Tokens - Use Design System values */
+  --uds-button-surface-primary-default: #009add;  /* From Design System, not brand */
+  --uds-surface-brand-primary: #e3f5fa;  /* From Design System */
+}
+```
+
+### Brand Override Block
+```css
+[data-brand="comphealth"] {
+  /* Brand Color Overrides */
+  --brand-color-primary-500: #644d7b;  /* CompHealth value */
+  
+  /* Component Tokens Override (if needed) */
+  --uds-button-surface-primary-default: var(--uds-color-primary-500);  /* References semantic token */
+}
+```
+
+**Cascade Flow**:
+1. `:root` sets `--brand-color-primary-500: #009add` (DS default)
+2. `[data-brand="comphealth"]` overrides `--brand-color-primary-500: #644d7b`
+3. `--uds-color-primary-500: var(--brand-color-primary-500)` automatically updates
+4. Component tokens that reference `--uds-color-primary-500` automatically update
+
+## Verification Checklist
+
+After applying fixes, verify in DevTools:
+
+1. **Check `:root` has no hard-coded brand values**:
+   - Search for `--uds-button-*` in `:root` - should be Design System values only
+   - Search for `--uds-surface-*` in `:root` - should be Design System values only
+
+2. **Check brand blocks contain overrides**:
+   - `[data-brand="comphealth"]` should have `--brand-color-*` variables
+   - `[data-brand="comphealth"]` should have component token overrides if they differ
+
+3. **Test brand switching**:
+   - Set `data-brand="comphealth"` on `<html>`
+   - Verify buttons/surfaces change color
+   - Set `data-brand="modio"` on `<html>`
+   - Verify buttons/surfaces change to Modio colors
+
+4. **Verify cascade**:
+   - `--uds-color-primary-500` should reference `var(--brand-color-primary-500)`
+   - Changing `--brand-color-primary-500` in brand block should update `--uds-color-primary-500`
+   - Component tokens should reference semantic tokens (or hard values if not color-derived)
+
+## Files to Modify
+
+1. `scripts/generate_structured_css.py`
+   - Lines 632-681: Remove brand injection logic
+   - Lines 1003-1005: Remove skip logic
+   - Lines 1045-1069: Update filtering logic
+   - Lines 564-611: Consider removing `ds_var_brand_overrides` tracking (or repurpose it)
+
+## Notes
+
+- **Preserving structure**: All variable names, output format, and collection structure remain unchanged
+- **Minimal changes**: Only removing problematic injection logic, not redesigning the system
+- **Cascade correctness**: After fixes, cascade will work as expected: Core → Brand primitives → Design System → Component tokens

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CHG Healthcare
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.lib.md

@@ -0,0 +1,103 @@
+# @chg/uds-components
+
+CHG Healthcare Unified Design System - React Component Library
+
+## Installation
+
+```bash
+npm install @chg/uds-components
+```
+
+## Usage
+
+```jsx
+import { Button, Chip, Avatar, Badge } from "@chg/uds-components";
+import "@chg/uds-components/styles.css"; // Required for component styles
+
+function App() {
+  return (
+    <div>
+      <Button appearance="primary">Click Me</Button>
+      <Chip label="Tag" />
+      <Avatar initials="JD" />
+      <Badge count={5} variant="red" />
+    </div>
+  );
+}
+```
+
+## Available Components
+
+### Layout & Structure
+- `Accordion`, `AccordionItem` - Expandable content sections
+- `Card` - Content container with styling
+- `Divider` - Visual separator
+- `Flex` - Flexbox layout helper
+- `ImageAspect` - Maintains image aspect ratios
+- `Steps` - Step indicator for multi-step flows
+- `Table` - Data table component
+- `Tabs`, `TabItem` - Tabbed navigation
+
+### Navigation
+- `ActionMenu` - Dropdown action menu with keyboard support
+- `Breadcrumb` - Navigation breadcrumbs
+- `Dropdown` - Dropdown select component
+- `Menu` - Navigation menu
+- `Pagination` - Page navigation
+
+### Form Controls
+- `Button` - Primary interaction element
+- `Checkbox` - Checkbox input
+- `Chip` - Tag/filter chips
+- `Datepicker` - Date selection
+- `Field` - Form field wrapper
+- `FileUpload` - File upload component
+- `Input` - Text input field
+- `PillToggle` - Toggle button group
+- `Radio` - Radio button input
+- `Slider` - Range slider
+- `Textarea` - Multi-line text input
+- `Toggle` - On/off toggle switch
+
+### Data Display
+- `Avatar` - User avatar with image or initials
+- `Badge` - Notification badge
+- `DotStatus` - Status dot indicator
+- `Icon` - Phosphor icon wrapper
+- `Key` - Keyboard shortcut display
+- `ProgressCircle` - Circular progress indicator
+- `ProgressIndicator` - Linear progress bar
+- `Status` - Status indicator component
+- `Tag` - Categorization tags
+
+### Feedback
+- `Toast` - Notification toast messages
+- `Tooltip` - Hover tooltips
+
+### Branding
+- `Branding` - Logo and brand assets
+
+## Design Tokens
+
+The component library uses CSS custom properties (variables) for theming. Import the styles to get all design tokens:
+
+```css
+@import "@chg/uds-components/styles.css";
+```
+
+Or include them in your build:
+
+```scss
+@use "@chg/uds-components/styles.css";
+```
+
+## Peer Dependencies
+
+This library requires:
+- `react` >= 17.0.0
+- `react-dom` >= 17.0.0
+- `react-router-dom` (optional, only needed for Card and Breadcrumb components)
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,177 @@
+# CHG Design System (UDS)
+
+A unified design system for CHG Healthcare brands, featuring React components, design tokens synced from Figma, and comprehensive documentation.
+
+## Overview
+
+This design system provides:
+
+- **40+ React Components** — Fully styled, accessible UI components
+- **Design Tokens** — Colors, spacing, typography, and more synced directly from Figma
+- **Multi-Brand Support** — Theming for CompHealth, Connect, LocumSmart, Modio, and Weatherby
+- **Figma Code Connect** — Bridge between design and development
+- **Documentation Site** — Interactive component demos and usage guidelines
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Start the documentation site
+npm start
+```
+
+The development server runs at [http://localhost:3000](http://localhost:3000).
+
+## Available Scripts
+
+### Development
+
+| Command | Description |
+|---------|-------------|
+| `npm start` | Start the documentation site in development mode |
+| `npm test` | Run tests in watch mode |
+| `npm run sass:watch` | Watch and compile SCSS files |
+
+### Design Tokens
+
+| Command | Description |
+|---------|-------------|
+| `npm run tokens:generate` | Fetch and generate tokens from Figma |
+| `npm run tokens:validate` | Validate token references |
+| `npm run tokens:compile` | Compile SCSS tokens to CSS |
+| `npm run tokens:watch` | Watch and compile token changes |
+
+### Library Build
+
+| Command | Description |
+|---------|-------------|
+| `npm run build:lib` | Build the component library for distribution |
+| `npm run build:lib:watch` | Build library in watch mode |
+| `npm run publish:lib` | Publish the library package |
+
+### Figma Code Connect
+
+| Command | Description |
+|---------|-------------|
+| `npm run codeconnect:publish` | Publish Code Connect mappings to Figma |
+| `npm run codeconnect:unpublish` | Remove Code Connect mappings |
+
+### Production
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build the documentation site for production |
+
+## Project Structure
+
+```
+├── src/
+│   ├── ui/                    # Component library
+│   │   ├── Accordion/
+│   │   ├── Button/
+│   │   ├── Card/
+│   │   └── ...
+│   ├── pages/                 # Documentation pages
+│   ├── styles/                # Global styles and tokens
+│   │   ├── _variables.scss    # Generated Figma variables
+│   │   ├── tokens.scss        # CSS custom properties
+│   │   └── _typography.scss   # Typography utilities
+│   └── assets/                # Images and static assets
+├── scripts/
+│   ├── index.js               # Token generation script
+│   ├── validate.js            # Token validation
+│   └── publish-lib.js         # Library publishing
+├── dist/                      # Built library output
+└── build/                     # Built documentation site
+```
+
+## Components
+
+The design system includes a comprehensive set of components:
+
+**Form Controls:** Button, Checkbox, Datepicker, Dropdown, Field, FileUpload, Input, Radio, Slider, Textarea, Toggle
+
+**Data Display:** Accordion, Avatar, Badge, Card, Chip, DotStatus, Icon, ImageAspect, Key, Status, Table, Tag, Tooltip
+
+**Navigation:** ActionMenu, Breadcrumb, Menu, Pagination, PillToggle, Steps, Tabs
+
+**Feedback:** ProgressCircle, ProgressIndicator, Toast
+
+**Layout:** Divider, Flex
+
+## Design Tokens
+
+Tokens are synced from Figma and include:
+
+- **Colors** — Brand colors, semantic colors, neutrals
+- **Spacing** — Consistent spacing scale
+- **Typography** — Font families, sizes, weights, line heights
+- **Border Radius** — Corner radius values
+- **Shadows** — Elevation and depth
+- **Animation** — Timing and duration values
+
+### Syncing Tokens from Figma
+
+1. Create a `.env` file with your Figma credentials:
+
+```env
+FIGMA_ACCESS_TOKEN=your_figma_token
+FIGMA_FILE_KEY=your_file_key
+```
+
+2. Run the token generation script:
+
+```bash
+npm run tokens:generate
+```
+
+## Using the Component Library
+
+### Installation in Your Project
+
+```bash
+npm install @chg/uds-components
+```
+
+### Usage
+
+```jsx
+import { Button, Card, Input } from '@chg/uds-components';
+import '@chg/uds-components/styles.css';
+
+function App() {
+  return (
+    <Card>
+      <Input label="Email" type="email" />
+      <Button variant="primary">Submit</Button>
+    </Card>
+  );
+}
+```
+
+## Browser Support
+
+- Chrome (last 2 versions)
+- Firefox (last 2 versions)
+- Safari (last 2 versions)
+- Edge (last 2 versions)
+
+## Contributing
+
+1. Create a feature branch from `main`
+2. Make your changes
+3. Ensure tests pass and components render correctly
+4. Submit a pull request
+
+## License
+
+See [LICENSE](./LICENSE) for details.

package/figma.config.json

@@ -0,0 +1,9 @@
+{
+  "codeConnect": {
+    "parser": "react",
+    "label": "React",
+    "include": ["src/ui/**/*.{tsx,jsx}"],
+    "exclude": ["**/node_modules/**", "**/dist/**", "build/**"],
+    "interactiveSetupFigmaFileUrl": "https://www.figma.com/file/LkIyThUA0oVNsDEAyOF7ER/Design-System--Components?node-id=18-2"
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@mich8060/chg-design-system",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@figma/code-connect": "^1.3.9",
+    "@phosphor-icons/react": "^2.1.10",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@testing-library/user-event": "^13.5.0",
+    "dotenv": "^16.6.1",
+    "node-fetch": "^3.3.2",
+    "prismjs": "^1.30.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^6.28.0",
+    "react-scripts": "5.0.1",
+    "web-vitals": "^2.1.4"
+  },
+  "codeConnect": {
+    "parser": "react"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "build:lib": "vite build --config vite.config.lib.js",
+    "build:lib:watch": "vite build --config vite.config.lib.js --watch",
+    "publish:lib": "node scripts/publish-lib.js",
+    "test": "react-scripts test",
+    "eject": "react-scripts eject",
+    "tokens:generate": "node scripts/index.js",
+    "tokens:validate": "node scripts/validate.js",
+    "tokens:compile": "sass scripts/tokens.scss tokens/tokens.css",
+    "tokens:watch": "sass --watch tokens/tokens.scss:tokens/tokens.css",
+    "codeconnect:publish": "code-connect publish",
+    "codeconnect:unpublish": "code-connect unpublish",
+    "sass:watch": "sass --watch src/styles/prism-custom.scss:src/styles/prism-custom.css"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ]
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.2.1",
+    "prettier": "3.8.1",
+    "sass": "^1.97.3",
+    "vite": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/package.lib.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chg/uds-components",
+  "version": "1.0.0",
+  "description": "CHG Healthcare Unified Design System - React Component Library",
+  "author": "Michael Stevens",
+  "license": "MIT",
+  "main": "uds-components.umd.js",
+  "module": "uds-components.es.js",
+  "exports": {
+    ".": {
+      "import": "./uds-components.es.js",
+      "require": "./uds-components.umd.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "uds-components.es.js",
+    "uds-components.es.js.map",
+    "uds-components.umd.js",
+    "uds-components.umd.js.map",
+    "styles.css",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css",
+    "**/*.scss"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chg-healthcare/uds-components.git"
+  },
+  "keywords": [
+    "react",
+    "components",
+    "ui",
+    "design-system",
+    "uds",
+    "chg"
+  ],
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-router-dom": {
+      "optional": true
+    }
+  }
+}