Skip to content

docs: add design system and implementation plan for scstem.org overhaul - #14

Open
CS-5 wants to merge 12 commits into
stagingfrom
claude/website-overhaul-plan-38czl6
Open

docs: add design system and implementation plan for scstem.org overhaul#14
CS-5 wants to merge 12 commits into
stagingfrom
claude/website-overhaul-plan-38czl6

Conversation

@CS-5

@CS-5 CS-5 commented Aug 27, 2026

Copy link
Copy Markdown
Member

Summary

This PR establishes the design system specification and complete implementation plan for rewriting scstem.org from Next.js to Astro. It includes the normative design document (DESIGN.md) and a detailed 11-phase execution plan with acceptance criteria for each phase.

Changes

DESIGN.md (new)

A comprehensive design system document covering:

  • Brand essence & voice: naming conventions, tone guidelines (energetic, concrete, community-proud)
  • Color system: semantic tokens for dark mode, surface hierarchy (recessed "machined pocket" cards), accent pairs with fill/text variants, program theme remapping via CSS custom properties
  • Typography: fluid type scale with clamp(), font families (Inter, Orbitron, Source Code Pro, Architects' Daughter), heading hierarchy
  • Spacing & elevation: consistent radius scale, shadow/inset treatments, motion tokens
  • Signature motifs: key-word emphasis, accent hairlines, engineering grid overlays, framed media, atmosphere devices (ambient pools, ghost numerals, ruler dividers, registration marks)
  • Scribed register: blueprint-style title blocks, lineart, labeled callouts, dimension annotations
  • Accessibility: AAA contrast requirements, focus states, reduced-motion handling
  • Component specifications: buttons, cards, forms, navigation, footer, hero sections with detailed anatomy

plan/00-overview.md (new)

High-level plan overview covering:

  • How to execute the 11-phase stack (GitHub stacked PRs via gh-stack)
  • 10 locked objectives (clean rewrite, content collections, zero framework runtime, Astro-native primitives, static output, brand-faithful refresh, cnfast-only, technical SEO, strictest tooling, agent configs)
  • 18 locked decisions (D1–D18) establishing constraints: no CMS now, dark-only initially, per-program themes, URL preservation, collection schemas, etc.

plan/01-foundation.md through plan/12-content-strategy.md (new)

Eleven phase specifications, each with prerequisites, objectives, and detailed tasks:

  1. Phase 01 — Foundation: Astro scaffold, toolchain (mise/pnpm, oxlint/oxfmt, ESLint, Prettier, TypeScript strictest), CI setup, agent config, legacy code moved to legacy/ directory
  2. Phase 02 — Design system: Tailwind v4 tokens, fluid type scale, self-hosted fonts, program themes, /styleguide proof page
  3. Phase 03 — Primitives: shadcn-convention Astro components (Button, Card, Badge, Input, Accordion, Dialog, etc.), zero-JS-by-default, agent skill for future porting
  4. Phase 04 — Content model: Astro Content Collections with zod schemas for sponsors, events, FAQ, news, robots, team photos; flat, CMS-friendly structure
  5. Phase 05 — App shell: BaseLayout, SEO component, JSON-LD builders, Navbar/Footer per DESIGN.md, 404 page
  6. Phase 06 — Homepage: Composed components (Hero, Section, FeatureCard, SponsorStrip, CtaBanner), owner design review gate
  7. Phase 07 — Remaining pages: About, Sponsors, Contact, Donate, Get Involved, Programs hub, FRC/FLL program pages (four sub-layers)
  8. Phase 08 — Events: EventLayout pattern for /openhouse and /programs/frc/kickoff driven by events collection, Countdown component, event JSON-LD
  9. Phase 09 — Assets & performance: Media pipeline (astro:assets), source re-encoding, hero video optimization, Lighthouse CI budgets as blocking gates
  10. Phase 10 — SEO completion: Sitemap/robots, OG images, structured-data audit, llms.txt for AI agents, analytics event taxonomy
  11. Phase 11 — Cutover: Parity verification, staging QA, production launch, cleanup
  12. Phase 12 — Content strategy (post-overhaul backlog): Copy revision, news cadence, program landing

https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn

claude added 12 commits August 27, 2026 14:55
@claude
Add website overhaul implementation plan
fa936ab 
Complete phased plan for the Next.js -> Astro rewrite: toolchain
(pnpm/mise/oxlint/oxfmt/ESLint/Prettier split), design system,
shadcn-convention Astro primitives, content collections, page ports,
event landing pattern, asset/performance budgets, SEO/AI-SEO,
analytics, and cutover. plan/00-overview.md records all locked
decisions from the planning interview.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Add DESIGN.md; settle design up front and drop private-path noindex r…
aadd9c9 
…ules

DESIGN.md is now authored with the plan (grounded in the extracted
legacy palette, fonts, and live-site audit) rather than deferred to
Phase 02, which becomes pure implementation. Phase 06's gate becomes a
conformance check. New decision D25: no private/internal content on
the main domain - _headers noindex reduced to preview/staging hosts
only, dropping /team/*, /image/*, /video/* and enabling media
indexing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Clarify outline-button-on-photo and logo-mark color exemption in DESI…
0789c6f 
…GN.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Encode design-review decisions in DESIGN.md and plan
4438f0d 
Settled in owner review against Brand Guidelines v1: brand-literal
recessed surfaces (#262626 page / #171717 machined-pocket cards, grid
floor on feature moments), AAA text ramp, fill-vs-text accent token
pairs for all brand colors, Science Blue as informational + reserved
light-theme primary, Source Code Pro as the data voice, engineering
grid motif replacing the circuit pattern, real logo lockups in chrome,
sticky header, /programs hub behind the nav dropdown, full-height
mobile menu, and brand naming rules. Recorded as D26; navbar/footer
specs and the new /programs page added to phases 02/05/07.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Add atmosphere layer to DESIGN.md
7ebe54c 
Between-section devices for the dark ground: ambient pools, ghost
section numerals (from the brand guidelines' section pages), ruler
dividers, and tint bands - exactly one per boundary, with a restraint
rule. Closes the flat/sterile-background review feedback.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Tune atmosphere layer: page-ground grid, stronger devices, registrati…
67811cf 
…on marks

The engineering grid now runs on the page ground itself (<=3%) so the
dark surface reads as the drawing sheet the pockets are cut into;
pools/numerals/ruler opacities raised per review; corner registration
marks added as a feature-pocket garnish.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Reject page-ground grid; ground stays smooth so pocket grid floors read
b9c4204 
Review finding: a page-level grid competes with the V2+V3 feature
pocket floors and dulls the recess effect. Grid stays scoped to
heroes, section breaks, and feature-pocket interiors; ground
modulation comes from pools, numerals, ruler dividers, tint bands,
and registration marks.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Adopt the scribed register from the official t-shirt art
dd0dd98 
New DESIGN.md motif family with the t-shirt art as normative
reference: highlight capsules (the Real Skills/Robots/Fun treatment),
the engineering-drawing title block, scribed wireframe lineart, and
labeled leader-line callouts - plus a register budget capping distinct
blueprint devices at 4 per viewport. Phase 02 gains the task of
sourcing the wireframe gear-bulb vector from the merch files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Add hand-markup register; ban pill UI
7b3cfbc 
Third metaphor layer: the engineer's hand markup over the machined
sheet - chalk ovals (replacing the rejected pill capsules),
highlighter swipes, chalk underlines, and sketch arrows, with a
draw-on entrance as the one sanctioned decorative animation. Machined
strokes stay perfectly straight; hand strokes stay imperfect - the
contrast is deliberate. Register budget covers all three layers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Markup variation rules, annotation hand, inline underlines, unified r…
c5df66d 
…adii

Per design review: every hand-markup device ships >=3 SVG path
variants (adjacent instances never match); highlighter swipes vary
rotation/inset/alpha; chalk underlines work inline under short phrases
as the sanctioned in-prose emphasis; sketch arrows may only target
handwritten annotation text (new Architects Daughter annotation face,
markup-only); machined/scribed layers stay perfectly geometric. Radius
scale unified to the one-end-mill system: 4/8/12, 16px and pills
retired.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Switch implementation flow to GitHub stacked PRs
12e5c6a 
The overhaul lands as one gh-stack: this plan/DESIGN branch is the
bottom layer targeting staging, each phase is a branch stacked on the
previous phase's branch, and the whole stack cascade-merges into
staging at cutover - no long-running astro-rewrite branch, no manual
merge sequencing. Restack rules, per-layer CI/preview notes, and
cutover mechanics updated; stale radius-xl references in phase 02
cleaned up and hand-markup primitives added to its task list.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@claude
Reference PR #14 as the bottom of the stack
7c5fcd3 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DU6XwSGRUDZtz5DuXjzKnn
@CS-5 CS-5 mentioned this pull request Aug 28, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@CS-5 @claude