Design System

OnRamp's design tokens — colors, typography, and shape — are defined once in design-system/DESIGN.md and generated into CSS/Tailwind/JSON artifacts. DESIGN.md is the single source of truth; this section documents and showcases what it produces.

This docsite's own theme is built from those same tokens, so what you see here is the palette in use.

Building UI with the design system

Tokens are only half the story — these guides cover how to apply them consistently in OnRamp UI:

• OnRamp UI Conventions (docs/design-system/conventions.md) — the compositional patterns: how to assemble PrimeVue + Tailwind into a polished OnRamp page. Page shell, card elevation, type hierarchy, KPI tile composition, color use philosophy, spacing rhythm, DataTable / Chart discipline, empty/loading/error states. The opinionated single source for "how to make it look professional, not just pass the linter."
• Forbidden patterns (docs/design-system/forbidden-patterns.md) — the canonical list of prohibitions (raw ramp, hex, !important, v3 names, .p-* scoped color, token-as-data, …), each with a grep pattern and fix. The single source both design-handoff skills and the rules file reference.
• UI rules (.claude/rules/ui-design-system.md) — the canonical rules: the stack, theming layers (token source vs. app override), the utility-first Tailwind + PrimeVue rulebook, the cssLayer model, v3→v4 component name map, severity vocabulary. Auto-loads for agents on app/ui-* edits. Deeper migration/theming detail is in the /primevue skill (.agents/skills/primevue/).
• AI Design → Vue SFC Workflow — landing a Claude Design bundle/artifact as Vue SFCs against the active preset.

Utility-first Tailwind + PrimeVue

Custom styling on the org app is utility-first Tailwind v4 on top of PrimeVue components themed by the active preset. Both apps run the layered cascade (cssLayer: true; layer order reset, primevue, portal-primevue-overrides, tw-utilities), so a Tailwind utility on the markup overrides a PrimeVue component without !important — the official PrimeVue + Tailwind integration.

• Layout / spacing / typography → Tailwind utilities (flex gap-4, p-4, text-sm). These non-color scales come from @theme in the generated tailwind.theme.css.
• Component look → PrimeVue preset + severity (meaning, not intensity).
• Color in markup → tailwindcss-primeui semantic utilities (bg-surface-*, text-muted-color, text-primary, border-surface) — scheme-aware and Aura-tracking, so dark: is rarely needed. Never a raw ramp utility (bg-purple-700) or hex.
• Scoped CSS / :deep() → escape hatch only, for deep PrimeVue internals and teleported overlays. Layout only, never color.

Color is single-source and flows one way:

DESIGN.md → preset primitives → Aura semantic mapping → runtime --p-* → primeui utilities

@theme carries non-color scales only (spacing / radius / typography); the color ramp lives in tokens.css as CSS vars (var(--color-*)) for decorative / escape-hatch use. So there's exactly one color vocabulary in markup — the scheme-aware primeui semantic utilities — with no raw-ramp second path to drift into.

Tokens at a glance

Group	Source token	Value
Brand primary	--color-primary
Brand purple	--color-brand-purple
Brand green	--color-brand-green
Body font	--font-body	system stack, 14px base
Radius (md / lg)	--radius-md / --radius-lg	8px / 16px

The swatches render live from the generated tokens.css, so this table can't drift from DESIGN.md — hex values are deliberately not written here.

The full ramps (black, blue, green, orange, pink, purple, red, yellow — each 50→950) live in the generated tokens.css.

Palette

HTML mocks

Standalone HTML design mocks belong in this section. Put the file under docs/public/, build it on the OnRamp tokens (import the generated tokens.css), and add a short landing page here that links to it. The docs skill ships a ready-to-fork HTML template and walks through the steps.

No mocks registered yet — this section is scaffolded for future design-system documentation.