# Designing Systems. Not Just Screens.

## Scope and implementation status

This is a portfolio documentation library and an interactive experiment. It does not replace the production PB.fit or Corpus applications. PB.fit remains a vanilla JavaScript PWA; Corpus remains a React application. The React components in this directory are a deliberately bounded demonstration layer based on their existing patterns.

| Evidence | Observed in the source | Consolidated in this study |
| --- | --- | --- |
| PB.fit, `d80a208` | CSS custom properties, explicit light/dark modes, configurable accent/shape/surface presets, shared icon/metric helpers, a component catalogue and design-system tests | JSON primitives, semantic aliases, component tokens, a React port and inspectable state examples |
| Corpus, `c614e89` | OKLCH semantic variables, Instrument Sans, olive/sage/sand materials, CVA button variants, Radix foundations, reusable TeacherTag and scheduling patterns | A portable JSON contract, a scoped demonstration library, role compositions and a proposed dark theme |

Source references are project-relative. Only fictional names, schedules and workout data appear in the examples. No patient data, authentication adapters, product credentials or storage clients are included.

## Decisions, not retroactive claims

The current products do not read these JSON files. Existing foundations were extracted, then normalized into a shared contract. Font and spacing scales are documented consolidation choices, not a claim that every original screen already follows them. Corpus colors use the hexadecimal equivalents documented in the source comments. Form-control borders and muted text are strengthened where needed for contrast. Existing product radii remain inside scoped specimens; the portfolio documentation shell stays square and editorial.

PB.fit dark mode exists in the product. Corpus and Editorial dark modes are proposals confined to these demonstrations. The original product source trees were not modified.

## Architecture

```
tokens/{brand}.json
  primitive → modes.{light|dark} → semantic aliases → component aliases
       ↓ resolveTokens (missing aliases and cycles fail)
       ↓ tokenCSS (aliases preserved as CSS var references)
assets/tokens.css
       ↓ [data-ds-brand][data-ds-mode] scope
React primitives → product patterns → application compositions
       ↓
live catalogue / properties / states / usage / source / exports
```

This is a small project token format using typed values and brace aliases; it is not a complete token interchange-standard implementation. A future external adapter must validate the destination schema rather than assume compatibility.

Each product documents 14 components: 10 shared primitives and 4 product patterns. All examples and application compositions import `source/components.jsx`. No screenshot substitutes for a working control. No component knows about a server, database, product role or account.

## Component contract

Primitives: Button, TextField, SelectField, Checkbox, Toggle, SegmentedControl, Status, Progress, Dialog, EmptyState.

PB.fit patterns: Metric, WorkoutCard, ExerciseRow, SetStepper.

Corpus patterns: ProfessionalTag, ClassSlot, WeekStrip, ScheduleTable. Metric is also reused in the composed operational overview; it is not counted again as a Corpus catalogue entry.

Domain patterns compose primitives. A button must not infer authorization from a disabled state. Product server functions and database policies remain the authority for availability, permissions and persistence.

## Applying the tokens to existing portfolio demonstrations

`adapters.css` maps the compiled PB.fit roles to the original PWA variables in the isolated, fictional app embed. Its existing markup, interactions and light/dark switch remain intact. The existing Corpus case specimen uses the same light roles for its background, action color and text. These are portfolio-only adapters; they do not migrate the products or establish a production dependency on this study.

## Accessibility contract

- Text and action foreground pairs are checked at 4.5:1; field borders and focus at 3:1.
- Controls use a 44px minimum target. Dense native table data remains readable and horizontally scrollable when required.
- A field has a visible label, associated description and `aria-invalid` when appropriate.
- Native checkbox, select, progress and dialog behavior is retained. Dialog supports Escape, focus containment and return to the trigger.
- States use words and shapes as well as color. Professional identity always includes a name.
- Motion is restricted to feedback and layout changes and removed under reduced-motion preferences.

These are tested behaviors in this documentation, not a WCAG certification or a completed assistive-technology audit.

## Handoff and contribution

1. Start from a task and an existing pattern before adding a component.
2. Prefer a semantic role over a new raw color. Add a primitive only when no current value fits.
3. Add both theme aliases; document when a mode is proposed rather than shipped.
4. Keep data, permissions and API side effects in the consuming application.
5. Add a catalogue story, relevant error/disabled/loading states and keyboard behavior.
6. Run `npm test` and `npm run build` from this directory; inspect desktop, tablet and mobile examples.
7. Review an exported token diff and a representative composed screen before release.

This study is version 0.1.0. Adoption is proposed incrementally: try one screen through the adapter, verify visual and behavioral differences, then migrate consumers only after review. No full product migration is claimed.

## Build and source

Requires Node.js with npm. From `systems/`, run `npm ci`, `npm test`, `npm run build`. The build validates aliases, produces scoped CSS, bundles React locally and generates the collection and the two system chapters. No runtime CDN is required. `pages.mjs` is the editorial source; `source/catalogue.js` is the component documentation source. Regenerate after changing tokens or components.

## Future Figma MCP handoff

Not connected or implemented here. A future adapter would map primitive/semantic names to Figma variables and modes, map React properties to component variants and keep stable identifiers in a reviewed mapping file. Begin with a read-only comparison of tokens and component contracts. Validate alias coverage, naming and property parity before allowing any write. Publishing libraries and account/plan requirements must be verified when that integration is actually commissioned; this demonstration depends on neither.

## Verification record

See [verification.md](verification.md) for the checks performed and their limits.