dt-design-system/CLAUDE.md

CLAUDE.md — DT Design System

Project Overview

Monorepo for the Dangerous Things design system. Six npm packages publish under @dangerousthings/*:

• tokens — canonical design tokens in TypeScript, compiled to JS and auto-generated as CSS custom properties
• web — CSS themes (bevels, forms, animations) consumed by web apps
• react — React web components wrapping web CSS
• react-native — React Native components built on React Native Paper
• tailwind-preset — Tailwind CSS v3 preset mapping DT tokens
• hex-background — 3D hexagon grid background (Three.js)

Two brand themes: dt (neon cyberpunk / beveled), classic (dark navy / magenta).

Build & Tooling

• Turbo orchestrates builds; packages/tokens must build first (dependency for web and react-native).
• Build everything: npm run build
• Typecheck everything: npm run typecheck
• Tokens build: tsc then node dist/scripts/generate-css.js
• Web build: node scripts/build.cjs (copies CSS, assembles brand token CSS, copies fonts)
• React Native build: tsc
• Versioning: Changesets (npx changeset, npm run version-packages, npm run release)

Architecture Rules

• Tokens are the single source of truth. Never hard-code color, typography, or shape values in web or react-native packages — always reference the tokens package.
• Web package is pure CSS — no JavaScript runtime except the optional theme-registry module.
• React Native components wrap React Native Paper and must list it (and react, react-native, react-native-svg, react-native-safe-area-context) as peer dependencies, never bundled dependencies.

Feature Parity

When adding or modifying a design token, component, or visual behavior, keep all four layers in sync:

1. Tokens — add/update the value in every brand file (packages/tokens/src/brands/{dt,classic}.ts) and in the shared type (packages/tokens/src/types.ts).
2. Web — if the token maps to a CSS component, update the relevant CSS file under packages/web/src/components/. Ensure the CSS custom property name matches the token path (e.g., --dt-color-brand-primary).
3. React — if there is a React web component wrapper, update or create the corresponding component in packages/react/src/components/.
4. React Native — update the corresponding component(s) under packages/react-native/src/components/ and ensure the theme provider maps the new token.

Parity Checklist (use before closing any PR)

• New tokens exist in all brand files with correct values
• Token types are updated if the shape of the token object changed
• CSS generation script produces the expected custom properties (npm run build:tokens then inspect dist/css/)
• Web CSS files reference the new/changed custom properties
• React web components are updated if applicable
• React Native components consume the new tokens via the theme
• All packages build cleanly (npm run build)
• TypeScript typechecks pass (npm run typecheck)

Testing

No test framework is configured yet. When adding tests, follow the guidance below.

Strategy

• Tokens: unit tests for token value correctness and CSS generation output. Verify every brand file satisfies the shared type. Snapshot the generated CSS files.
• Web: visual regression tests or snapshot tests for the compiled CSS. Ensure each brand's generated stylesheet contains expected custom properties.
• React Native: component rendering tests with React Native Testing Library. Test that each component renders without errors under every brand theme. Test interactive behaviors (press, toggle, expand).

Conventions (apply once a framework is added)

• Place test files next to source: foo.ts → foo.test.ts, DTButton.tsx → DTButton.test.tsx.
• Name test blocks clearly: describe("DTButton"), it("renders in contained mode").
• Run tests via Turbo: add a test task to turbo.json and per-package test scripts.
• CI should run turbo run test alongside build and typecheck.

Maintenance

Adding a New Component

1. If it needs new tokens, add them to all brand files and types first.
2. If there is a web equivalent, add a CSS file in packages/web/src/components/.
3. Create a React web component wrapper in packages/react/src/components/DTFoo.tsx and re-export from packages/react/src/index.ts.
4. Create the React Native component in packages/react-native/src/components/DTFoo.tsx and re-export from packages/react-native/src/index.ts.
5. Create a changeset: npx changeset — select affected packages and describe the change.

Adding a New Brand

1. Create packages/tokens/src/brands/newbrand.ts implementing the full BrandTokens type.
2. Re-export it from packages/tokens/src/index.ts.
3. The CSS generation script will pick it up automatically.
4. Add the brand to the React Native DTThemeProvider brand union.
5. Update this file and the README.

Modifying Tokens

• Always start in packages/tokens/src/types.ts if the token shape changes.
• Update every brand file — the TypeScript compiler will flag missing properties.
• Rebuild tokens (npm run build:tokens) and verify the generated CSS before touching downstream packages.

CI

GitHub Actions runs on push to main and on PRs:

• Builds across Node 18, 20, 22
• Runs typecheck
• Validates changesets on PRs (npx changeset status)

Code Style

• TypeScript strict mode.
• CSS uses BEM-ish class names prefixed with dt- (e.g., .dt-bevel-card).
• React Native components are prefixed DT (e.g., DTButton).
• Keep files focused — one component per file, one brand per file.

Storefront Component Migration — Implementation Reference

The DT Shopify Storefront (dt-shopify-storefront) is the genesis project for this design system. The storefront features documented below have been migrated into the design system. This section serves as a reference for the implemented components and their locations.

Implemented Features

Feature	CSS (web)	React Component	Notes
Card Color Modes	.mode-normal, .mode-emphasis, .mode-warning, .mode-success, .mode-other in bevels.css	DTCard	Five modes with *-selected variants at 70% opacity
Card Progress Bar	.dt-card-progress in bevels.css	DTCard (progress prop)	Vertical left-edge bar, 0-100%, fills on hover
Card Chip Badges	.dt-badge-overlay in bevels.css	DTBadgeOverlay	Positioned bottom-right, mode-color-aware
Card Hover/Selected	.card.selected and hover states in bevels.css	DTCard	Fills with var(--dt-card-color-selected)
Staggered Container	.dt-stagger-container in animations.css	DTStaggerContainer	CSS nth-child staggered animation-delay
Animation Library	animations.css	--	dt-scale-in, dt-fade-in, dt-slide-up, dt-pulse, dt-ping, dt-spin, transition utilities
Filter System UI	.dt-menu-item, .dt-filter-header, .dt-filter-overlay in forms-dt.css	DTMenu, DTMobileFilterOverlay	Nested menus, filter accordions, mobile overlay
Feature Legend	feature-legend.css	DTFeatureLegend	Icon grid with rotated labels, mode-colored header, feature states
Theme Branching	[data-brand="dt"] / [data-brand="classic"] CSS scoping	--	No JS conditionals needed; CSS handles visual differences
Scrollbar Styling	scrollbar.css (.dt-scrollbar)	--	Thin scrollbar with mode-normal color

Card color modes reference:

Mode	Token	Default (DT dark)	Use Case
mode-normal	--color-primary	#00FFFF cyan	Default product cards
mode-emphasis	--color-secondary	#FFFF00 yellow	Highlighted/selected states
mode-warning	--color-error	#FF0000 red	Lab products, warnings
mode-success	--color-accent	#00FF00 green	Positive/success states
mode-other	--color-other	#FF00FF magenta	Bundles, alternative states

Theme branching differences (handled by CSS, not JS):

Aspect	Cyberpunk (data-brand="dt")	Clean (data-brand="classic")
Clip-paths	Heavy bevels	border-radius: 0.75rem
Colors	Neon (#00FFFF, #FF00FF)	B&W or muted tones
Hover effects	Pulse glow animations	None
Typography	Tektur	system-ui sans-serif
Text shadows	0 0 8px var(--mode)	None
Borders	Thick neon (5px top)	Subtle 1px

Icon Set — Product Features & Filtering

Canonical icon set for the DT design system, sourced from react-icons.

Product Feature Icons (react-icons/md — Material Design):

Feature	Icon	Package
Illumination	MdLightbulbOutline	react-icons/md
Visibility/Glow	MdOutlineVisibility	react-icons/md
Data Sharing	MdOutlineMobileScreenShare	react-icons/md
UID Cloning/Magic	MdOutlineCopyAll	react-icons/md
Payment/NFC	MdOutlineCreditCard	react-icons/md
Smartphone Compat	MdOutlinePhonelinkRing	react-icons/md
Access Control	MdOutlineVpnKey	react-icons/md
Sensors	MdOutlineThermostat	react-icons/md
NFC Sensing	MdOutlineSensors	react-icons/md
Fitness/Bio	MdOutlineFitbit	react-icons/md
Vibration	MdOutlineVibration	react-icons/md
Exploration	MdOutlineExplore	react-icons/md
Cryptography	LuBinary	react-icons/lu
Digital Security	FaUserShield	react-icons/fa
Temperature (alt)	BsThermometerHalf	react-icons/bs

UI Control Icons:

Control	Icon	Package
Filter toggle	MdFilterList	react-icons/md
Expand/collapse	MdExpandMore	react-icons/md
Close/dismiss	MdClose	react-icons/md
Dropdown arrow	MdOutlineKeyboardArrowDown	react-icons/md
No image placeholder	MdOutlineHideImage	react-icons/md
More details	CgMoreR	react-icons/cg
Loading spinner	FaSpinner	react-icons/fa6
Cart	FaCartShopping	react-icons/fa6
Add to cart	FaCartPlus	react-icons/fa6
Search	FaMagnifyingGlass	react-icons/fa6
Back	FaArrowLeft	react-icons/fa6
User (logged in)	FaUser	react-icons/fa6
User (logged out)	FaUserSlash	react-icons/fa6
Delete	FaTrash	react-icons/fa

Custom SVG Icons (ThemeToggle.tsx):

• Sun icon (24x24) — switch to clean theme
• Terminal/matrix icon (24x24) — switch to cyberpunk theme

Icon display standard: Feature icons render at 42px in the UseCaseLegend grid. UI icons at 1.5em. Icons inherit color from their parent's --mode variable.

Known Issues

(none currently)