Foundations

Shared rules before surface-specific choices.

The foundation layer is the part of the system that should not drift. It defines the brand contract, token model, type system, theme behavior, and the rules for where visual decisions belong.

Foundation pages

Colours

Brand source colours, semantic tokens, and theme comparisons.

Gradients

Approved gradient tokens and where they belong in the shared system.

Typography

Fonts, heading scales, and marketing/app type roles.

Spacing

The core spacing scale and how density stays shared across surfaces.

Grid & Layout

Shared page-width and surface rhythm rules defined by current layer tokens.

Core foundation groups

Identity and voice

Explain what stays consistent across every Gensudo surface.
Document tone decisions separately for marketing and app experiences.
Keep onboarding under the app surface even when it carries some brand warmth.

Tokens and themes

`--color-primary`, `--color-text-muted`, and other semantic tokens should drive shared styling.
`body.theme-default` and `body.theme-dark` override semantic tokens rather than component CSS one by one.
Layer variables should handle surface differences before a component is forked.

Accessibility and motion

Focus, contrast, and text clarity are cross-surface rules.
Motion stays token-driven through shared durations and easing.
Shared components should inherit theme-safe behavior rather than hardcoded exceptions.

Current token contract

The current repo already documents the semantic token groups in `Docs/brand-system/tokens.md`. The site mirrors those groups and keeps them tied to the real shared CSS layer.

Color tokens: `--color-primary`, `--color-surface-base`, `--color-text-heading`, `--color-overlay`

Typography tokens: `--font-heading-stack`, heading scales, marketing display size, app title size

Layout tokens: spacing scale, radius scale, shadow scale, motion duration and easing

Layer classes: `body.brand-layer-marketing` and `body.brand-layer-app`

Decision rule

Start with shared foundations. If the change belongs everywhere, it goes into `packages/brand`. If it affects reusable structure, it belongs in `packages/ui`. Only after those options are exhausted should a route carry one-off layout styling.

1. Reuse an existing token.
2. Reuse an existing shared component or class.
3. Extend a shared primitive if the pattern is repeated.
4. Add a new semantic token or primitive when the pattern becomes shared.
5. Keep styling local only when the need is truly one-off.