Main Confidence / confidence (push) Failing after 40s

Details

feat: implement website visual foundation (#251 )

## Summary
- implement the website-only visual foundation for apps/website
- formalize semantic tokens, typography, spacing, surfaces, and shared CTA/navigation primitives
- align landing, trust/legal, and content-heavy routes plus Playwright smoke coverage with the new foundation

## Validation
- corepack pnpm build:website
- corepack pnpm --filter @tenantatlas/website exec playwright test

## Scope
- website-only change set for spec 214
- no apps/platform runtime coupling introduced

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #251

2026-04-19 07:19:58 +00:00

7.8 KiB

Raw Blame History

Data Model: Website Visual Foundation

Overview

This feature introduces no database schema. The model is a website-local design contract expressed through tokens, primitive semantics, and page-family consistency rules inside apps/website.

Entities

Website Visual Foundation

Purpose: The canonical visual contract for apps/website.
Key fields:
- scope (apps/website only)
- toneKeywords
- disallowedTraits
- pageFamilies
- accessibilityBaseline
- shadcnUsageMode
Relationships:
- Owns many Token Role entries
- Owns many Typography Role entries
- Owns many Spacing Rule entries
- Owns many Surface Rule entries
- Owns many Interaction Contract entries
- Owns many Primitive Contract entries
- Owns many Page Consistency Rule entries
Validation rules:
- Must remain explicitly local to apps/website
- Must explicitly exclude apps/platform, Filament theming, and shared cross-surface obligations
- Must define both desired tone and disallowed visual patterns

Token Role

Purpose: A semantic token used to express color, surface, border, radius, or shadow meaning.
Key fields:
- name
- category (color, surface, border, radius, shadow)
- semanticPurpose
- defaultValueSource
- allowedContexts
Relationships:
- Belongs to Website Visual Foundation
- May be referenced by many Primitive Contract entries
- May be referenced by many Page Consistency Rule entries
Validation rules:
- Required color roles include background, foreground, muted, muted-foreground, card, card-foreground, border, input, primary, primary-foreground, secondary, secondary-foreground, accent, accent-foreground, success, warning, destructive, and info
- Primaries must be used intentionally and not as the dominant surface color
- Status roles must remain semantic rather than decorative

Typography Role

Purpose: A named text role that governs hierarchy and readability.
Key fields:
- name
- intent (display, page, section, card, body, small, eyebrow, helper)
- fontFamily
- weight
- tracking
- lineHeight
Relationships:
- Belongs to Website Visual Foundation
- May be referenced by many Primitive Contract entries
- May be referenced by many Page Consistency Rule entries
Validation rules:
- Required roles include display or hero, page, section, card, body, small, eyebrow or label, and UI label or helper text
- Body and small text must stay readable on long-form pages
- Headlines must read as calm and precise rather than aggressive or novelty-first

Spacing Rule

Purpose: A repeatable spacing decision at page, section, or component level.
Key fields:
- level (page, section, component)
- density
- gapStrategy
- maxWidthBehavior
- rhythmIntent
Relationships:
- Belongs to Website Visual Foundation
- May constrain many Primitive Contract entries
- May constrain many Page Consistency Rule entries
Validation rules:
- Must define page spacing, section spacing, and component spacing
- Must support density shifts between hero-led and text-heavy layouts without abandoning the system
- Must avoid page-by-page optical tweaking as the default mechanism

Surface Rule

Purpose: Defines one level of content containment or emphasis.
Key fields:
- name (page-background, default-content, card, elevated, muted-inset, highlighted)
- emphasisLevel
- borderBehavior
- shadowBehavior
- intendedUse
Relationships:
- Belongs to Website Visual Foundation
- May be used by many Primitive Contract entries
- May be referenced by many Page Consistency Rule entries
Validation rules:
- Surface differences must communicate structure rather than decoration alone
- Cards must group meaningful content, not appear arbitrarily as style wrappers
- Shadows must remain restrained and border-led clarity must stay primary

Interaction Contract

Purpose: Governs semantic behavior for interactive elements.
Key fields:
- elementType (button, link, input)
- variantSet
- focusBehavior
- errorBehavior
- emphasisRules
Relationships:
- Belongs to Website Visual Foundation
- May be used by many Primitive Contract entries
Validation rules:
- Button hierarchy must at least cover primary, secondary, and low-emphasis or ghost
- Links must distinguish navigation intent from inline/supportive CTA behavior
- Inputs must share height, border, focus, and error-state logic across the website

Primitive Contract

Purpose: A reusable website building block that carries semantic and visual rules.
Key fields:
- name
- category (navigation, hero, section, grouping, cta, trust)
- backingComponent
- allowedVariants
- requiredTokenRoles
- defaultSpacingRule
Relationships:
- Belongs to Website Visual Foundation
- May reference many Token Role, Typography Role, Spacing Rule, and Surface Rule entries
- May be evaluated by many Page Consistency Rule entries
Validation rules:
- Required primitive groups include navigation, hero, section, content grouping, CTA, and trust primitives
- Primitive APIs must reinforce the foundation instead of allowing unrestricted local overrides
- Existing Astro primitives remain the primary implementation targets

shadcn Usage Policy

Purpose: Defines how shadcn/ui concepts may enter the website codebase.
Key fields:
- mode (adapted-locally)
- allowedUses
- forbiddenUses
- reviewExpectations
Relationships:
- Belongs to Website Visual Foundation
- Constrains many Primitive Contract entries
Validation rules:
- Library patterns must be adapted to website-owned tokens and primitives
- Uncontrolled default styling must not become the website’s visual language
- The policy must not implicitly require React or a second component runtime

Page Consistency Rule

Purpose: A cross-page rule that keeps the website coherent across route types.
Key fields:
- pageFamily
- contentWidthStrategy
- headingHierarchy
- sectionRhythm
- ctaPlacementLogic
- footerExpectation
Relationships:
- Belongs to Website Visual Foundation
- Applies to many routes in apps/website/src/pages
- References many Primitive Contract entries
Validation rules:
- Must cover at least landing/product, trust/legal, and content-heavy page families
- Must enforce one recognizable website rhythm across those page families
- Must prevent pages from inventing competing CTA or surface hierarchies

Relationship Summary

Website Visual Foundation owns many Token Role
Website Visual Foundation owns many Typography Role
Website Visual Foundation owns many Spacing Rule
Website Visual Foundation owns many Surface Rule
Website Visual Foundation owns many Interaction Contract
Website Visual Foundation owns many Primitive Contract
Website Visual Foundation owns many Page Consistency Rule
Primitive Contract references Token Role, Typography Role, Spacing Rule, and Surface Rule
Page Consistency Rule evaluates routes through the required Primitive Contract set
shadcn Usage Policy constrains how future primitives are authored or adapted

State / Lifecycle Notes

No persisted runtime states are introduced.
The foundation is repo-owned truth: it is expressed through shared styles, primitive APIs, and representative page composition rather than a database or application state machine.
A primitive or page is compliant when it maps to the defined foundation entities without inventing a competing local visual rule.

7.8 KiB Raw Blame History Unescape Escape