UDS Sample Application (Spec-driven + SCSS + Multi-brand + Governed App Shell)

This repo is a working reference implementation showing:

• Token-driven SCSS architecture (primitives → semantics → brands)
• Design-system components styled with SCSS (BEM, no raw values)
• Spec-driven component contracts (spec objects in code)
• Canonical component template + spec template
• A governed, configurable application shell with routing (routing lives in the shell)
• Brand + theme applied at the shell root
• Slot-based shell regions + structured layout config
• Linting “lockdown” (ESLint + Stylelint) and a CLI scaffold generator

Quick start

npm install
npm run dev

Scripts

• npm run dev – start Vite dev server
• npm run build – production build
• npm run preview – preview build
• npm run lint – eslint
• npm run lint:styles – stylelint for scss
• npm run format – prettier
• npm run generate:component -- Name – scaffold a new component folder from the canonical template

See /docs for the full methodology and governance model.

• Claude Rules – conventions and constraints for AI-assisted development in this repo
• AI Implementation Learnings – validated integration guidance and corrected component API assumptions
• Project Learnings Log – living, prompt-by-prompt implementation constraints and guardrails
• Consumer Project Setup – copy-paste setup guide for integrating UDS in a new app
• Runtime Tokens Migration – typed token exports and generated token CSS usage
• Theming Engine API – createTheme/createBrand/ThemeProvider architecture and usage
• Theming Platform API – formal public theming layer, architecture, and usage
• AI-Native Architecture – machine-readable metadata, patterns, and AI export strategy
• AI CI Enforcement – governance pipeline and merge-blocking validation flow

NPM package quick start

Install the package and required peer dependencies:

npm i @mich8060/unified-design-system react react-dom react-router-dom @phosphor-icons/react

Import components and styles:

import { AppShell, Button, Flex, Menu, Text, TextInput } from "@mich8060/unified-design-system";
import "@mich8060/unified-design-system/styles.css";

Runtime token primitives are also available as typed exports:

import { spacingTokens } from "@mich8060/unified-design-system/tokens/spacing";
import { runtimeTokens } from "@mich8060/unified-design-system/tokens";
import "@mich8060/unified-design-system/tokens.css";

AI metadata is available from a dedicated subpath:

import { UDS_AI_MANIFEST, UDS_FLOW_PATTERNS } from "@mich8060/unified-design-system/ai";

Common prop pitfalls

• Button uses appearance, not variant
  • valid values: primary, soft, outline, text, ghost, disabled, destructive
• Text requires a variant value such as heading-32 or body-16
• TextInput icon placement uses iconPosition with left or right
• Menu mode uses light or dark

Exported constants

Use exported constants to avoid guessing valid values:

import {
  BUTTON_APPEARANCES,
  TEXT_VARIANTS,
  TEXT_WEIGHTS,
  TEXT_INPUT_STATES,
  ICON_APPEARANCES
} from "@mich8060/unified-design-system";