Skip to content

docs: restructure DESIGN.md into Geist-inspired foundations + docs/ui product rules - #707

Merged
YaelAnaya merged 3 commits into
mainfrom
docs/geist-design-foundations
Aug 20, 2026
Merged

docs: restructure DESIGN.md into Geist-inspired foundations + docs/ui product rules#707
YaelAnaya merged 3 commits into
mainfrom
docs/geist-design-foundations

Conversation

@YaelAnaya

@YaelAnaya YaelAnaya commented Aug 19, 2026

Copy link
Copy Markdown
Collaborator

What changed

Documentation-only restructuring of the frontend design documentation. DESIGN.md is rewritten as a concise Geist visual-foundations and interaction contract (Purpose, Philosophy, Foundations, Component Principles, Responsive, Interaction, Accessibility, Content and Copy, Implementation Boundaries — 1453 → 437 lines). Every product rule it used to hold is relocated, not deleted:

  • docs/ui/product-principles.md — data-first, density on data surfaces, action-forward screens, never-disable-without-explanation, blast-radius confirmations, the authoritative product status mapping, number formatting, list/section rules, tabs, the Home and project-view screen rules, component contracts, and the current layout specifics (page/dialog widths).
  • docs/ui/navigation.md — ancestor chains and breadcrumbs, the rail's membership rule and widths, URL state ("not everything selectable is a place"), Back semantics, callbacks-not-routes.
  • docs/ui/annotator.md — the whole annotation-workspace contract: top bar zones, side panel regions, tool strip, frame gallery, zoom and the device model, read-only mode, the stage, shape rendering, provenance and confidence rules.
  • docs/architecture/frontend/ui-core.md — gains the Libraries section (technology constraints moved out of the visual contract).
  • Cross-references repointed: CONTRIBUTING.md, docs/README.md, docs/ui.md, docs/annotations.md, architecture READMEs, two .agents/skills files; the three new pages registered in docs-site/src/sidebar.mjs.

Foundation changes at the documentation level: primitive-scale + semantic-alias color model (light/dark-ready) with stage kept as a VisionSet-specific token; brand separated from functional semantics (the exactly-two-sites/count rules removed); Geist Sans/Mono with semantic type roles; radius by material level (6/12/16/full); materials replacing generic shadow tiers; action hierarchy replacing the one-filled-button count (and the button-goes-green-for-save principle removed); a general async-feedback baseline replacing issue-specific timing history; Title Case for labels / sentence case for prose replacing sentence-case-everywhere; copy bans replaced by principles.

No production file changed: nothing under frontend/, src/, or tests/.

Deliberate tensions, reported

  • The task spec asked to remove tests based on counting filled buttons / brand sites; it also declares the phase documentation-only with frontend/ui-core/src/screens/* out of scope. The tests stay (they enforce the current, unchanged implementation); removing them belongs to the token/primitive implementation phase. Until then, tests/scripts/design_tokens.test.mjs's brand-site roster and the screen-level button-count tests enforce rules DESIGN.md no longer states — they pin the implementation, not the contract.
  • The parallel shadcn migration branches (feat/shadcn-foundation, feat/shadcn-primitives) describe the same target direction from the implementation side; sequencing them against this branch is a review decision.

Found, not fixed

  • tests/scripts/favicon.test.mjs asserts hex #eb5a47 as "the Robomous accent" while the brand token is #e85d44 — pre-existing, out of scope here.
  • docs/annotations.md's showcase section still describes v1-era demo styling (#d0d7de borders, "Robomous orange as accent"); it describes the demo page and predates this change.

Test plan

All checks ran inside Linux Docker (visionset-gate:latest, which clones the committed branch from the repo mounted read-only, so line endings materialize as in CI):

docker run --rm --ipc=host -v "C:/Users/yaela/dev/VisionSet:/src:ro" visionset-gate:latest \
  bash -c 'git clone -b docs/geist-design-foundations /src /work && cd /work && \
           pnpm install --frozen-lockfile && pnpm test:scripts && \
           pnpm --dir docs-site install --frozen-lockfile && bash scripts/check.sh docs'
  • pnpm test:scripts → 107 pass / 0 fail (includes docs_links, docs_sidebar, design_tokens).
  • bash scripts/check.sh docs → PASSED (site build, deterministic projection, 4260 internal links across 47 pages resolve).

Browser and python suites are untouched by this diff; CI runs the exhaustive matrix.

#706 and the shadcn branches are untouched.

@YaelAnaya
YaelAnaya merged commit dffb74c into main Aug 20, 2026
15 checks passed
@YaelAnaya
YaelAnaya deleted the docs/geist-design-foundations branch August 20, 2026 00:37
JArmandoAnaya pushed a commit that referenced this pull request Aug 21, 2026
docs: restructure DESIGN.md into Geist-inspired foundations + docs/ui product rules
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant