Skip to content

DesignSystem

Jump to bottom
Edgar Mesquita edited this page Jul 5, 2026 · 4 revisions

Photon Design System

The design system behind the write-once components: a complete token/component specification (authored with Claude Design, preserved in-repo at docs/design/Photon-Design-System.dc.html — the source of truth) implemented as typed C# tokens in eQuantic.UI.Primitives and consumed by every realization target.

Token layers (§01–§09)

  • Colors — every color is a paired light/dark ColorToken; components never hold raw colors. Interactive variants resolve five sub-tokens (Base, OnBase, Pressed — a real token, not an overlay — Subtle, OnSubtle). Disabled is not a color: it's a 38% opacity group.
  • Type scale — role-driven (Display … BodyM, Caption, Label) with Dynamic Type clamps per role.
  • Spacing (Space.S1–S16, 4dp base, gap-owned — no margin exists), radius (Radius.Xs–Full, engine-clamped), icon sizes (§07 whitelist 16/20/24/32 — arbitrary sizes throw), touch (≥48dp hit contract), elevation (one analytic shadow per node), motion (durations + curves + spring).

Spec fidelity is tested, not aspired to

  • Token values are pinned; WCAG contrast is recomputed in tests for every claimed pair.
  • Component metrics come from the spec tables (e.g. Button's size table: 32/40/48/56 heights) and are asserted on every axis: C# web realizer pins, native golden images (light + dark), transpiled-fixture execution in vitest.
  • The style resolver rules (derived Outline/Ghost/Link variants, pressed-as-token-swap, focus double-ring) live in target-neutral C# (ButtonStyles).

The "generated, never hand-written" rule

Client-side artifacts carrying design-system values are generated from the C# single source and byte-pinned in CI (a drift fails the build; env-var flows regenerate):

Artifact Generator Regenerate with
Normative stylesheet (custom properties, .eq-type-*, .eq-elevation-*, motion vars) PhotonCssGenerator (pure function — tested per value)
design-system.generated.ts (tokens, theme object, Button size table) DesignSystemTsGenerator EQ_UPDATE_DESIGN_TS=1
icons.generated.ts (glyph path data) IconTsGenerator EQ_UPDATE_ICONS_TS=1
Embedded transpiled component modules live eqc output EQ_UPDATE_TRANSPILED=1

The same rule powers hydration: SSR (C# realizer) and client lowering (TS) are held byte-identical by cross-pinned literals in both test suites.

Icons pipeline (spec A10)

A curated Icons enum (16 glyphs and growing) with the path data living once in the C# IconRegistry (24×24 single-path alpha masks): the web emits inline <svg fill="currentColor"> (the tint rides the color token exactly like text), the TS side consumes the generated module, and the future native glyph atlas rasterizes from the same registry. Outline ↔ filled are distinct glyphs; icons ignore Dynamic Type.

Clone this wiki locally