Scaffold design engineering playground

Next.js 16 + TypeScript + Tailwind v4 + Motion project showcasing interface components built on semantic design tokens: - Light/dark/system theming from one CSS variable set, with a pre-paint script so a saved theme never flashes - Button, Switch and SegmentedControl with keyboard support, ARIA semantics and spring motion that respects reduced-motion - Vitest + Testing Library tests, including a token-coverage test - /tokens page documenting colour and motion tokens Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-09 03:52:46 +00:00
parent 3d9c5cef51
commit 7af2315316
33 changed files with 9526 additions and 1 deletions
@@ -1,2 +1,66 @@
-# typescript-project
+# Design Engineering Playground

+A TypeScript project for small interface components, built the way a design
+engineer would build them. Each one uses shared design tokens, works with a
+keyboard and a screen reader, and has motion that respects the user's settings.
+
+## What's here
+
+| Piece                                                             | Details worth noticing                                                                                                                                                                                           |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Design tokens** (`src/app/globals.css`, `src/tokens/tokens.ts`) | Semantic colour names such as `surface`, `muted` and `accent`, never raw hex values in components. Light, dark and system themes come from one variable swap. A test fails if a token is missing from any theme. |
+| **Button**                                                        | Primary, secondary, ghost and danger variants. Spring press feedback. A loading state that keeps the button's width and its accessible name, and sets `aria-busy`.                                               |
+| **Segmented control**                                             | A WAI-ARIA radio group with a roving tabindex. Arrow, Home and End keys work. One shared-layout indicator glides between options.                                                                                |
+| **Switch**                                                        | `role="switch"`. Works controlled or uncontrolled through `useControllableState`. The label is clickable and the description is wired to `aria-describedby`.                                                     |
+| **Theme toggle**                                                  | An inline pre-paint script means no flash on reload. Reads the saved preference through `useSyncExternalStore`, so hydration stays safe.                                                                         |
+| **Motion system**                                                 | Named springs and durations in `tokens.ts`. `MotionConfig reducedMotion="user"`, plus a CSS fallback for reduced motion.                                                                                         |
+
+## Stack
+
+Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS v4, Motion,
+Vitest and Testing Library, ESLint, and Prettier with Tailwind class sorting.
+
+## Getting started
+
+```bash
+npm install
+npm run dev        # http://localhost:3000
+```
+
+| Script           | What it does                                                         |
+| ---------------- | -------------------------------------------------------------------- |
+| `npm run check`  | Runs typecheck, lint, format check and tests. Run it before pushing. |
+| `npm test`       | Unit and accessibility tests (Vitest + Testing Library)              |
+| `npm run build`  | Production build. Every page is statically prerendered.              |
+| `npm run format` | Runs Prettier, which also sorts Tailwind classes                     |
+
+## Structure
+
+```
+src/
+  app/                 routes: / (component specimens), /tokens
+  components/ui/       the reusable components and their tests
+  components/site/     page chrome and demos
+  hooks/               useControllableState
+  lib/                 theme store, cn()
+  tokens/              token metadata, motion presets, token tests
+```
+
+## Principles
+
+1. **Tokens, not values.** Components use semantic names only, so a theme is just data.
+2. **Accessible by construction.** Tests query by role and accessible name,
+   the way assistive technology does. A broken label fails the build.
+3. **Motion with intent.** A few named springs keep every interaction feeling
+   like one system, and reduced-motion users get instant state changes.
+4. **No layout shift.** Loading states, theme changes and hover effects never move
+   surrounding content.
+
+## Roadmap
+
+- [ ] Command menu (⌘K) with fuzzy search and list virtualisation
+- [ ] Tooltip and popover with collision-aware positioning
+- [ ] Toast stack with swipe-to-dismiss
+- [ ] Playwright visual regression and axe checks in CI
+- [ ] Case-study write-ups for each component: the problem, the options, and the decision
+- [ ] Deploy (Vercel) and link from a portfolio