# DESIGN.md
- describes site wide design directions and inspiration

Status: Proposed visual direction (not pixel-exact reverse engineering)
References: 
- https://meeko-template.framer.website/
- https://meeko-template.framer.website/blog/design-choices-that-age-well-and-the-ones-you-will-regret-later

## Design goal
Build an original, accessible, responsive website for SHAPE (Spec-driven, Human-led, Agentic, Product, Engineering). Take inspiration from Meeko's pastel editorial aesthetic, bold typography, thin borders, generous whitespace, rounded cards, and friendly but restrained details. Do not copy the template's copyrighted images, text, illustrations, brand, or exact layout.

## Character
Clear, approachable, confident, contemporary, precise. Visual warmth on overview pages; increasing information density and restraint on technical documentation pages. Avoid generic dark AI gradients, neon, glassmorphism, and gratuitous animations.

## Proposed design tokens (starting values; not measured from Meeko)
- `--color-background: #F0EFFF` (soft lavender)
- `--color-surface: #FFFFFF`
- `--color-surface-subtle: #FAFAFF`
- `--color-text: #161616`
- `--color-text-muted: #555563`
- `--color-border: #292929`
- `--color-accent-lavender: #DAD8FF`
- `--color-accent-pink: #F8DCE8`
- `--color-accent-yellow: #FBE59B`
- `--color-accent-blue: #DBEFFB`
- `--color-focus: #3448BC`
- `--radius-card: 20px`
- `--radius-button: 999px`
- `--border-thin: 1px solid var(--color-border)`
- `--container-width: 1200px`
- `--content-width: 760px`

Colors are approximate design proposals, not extracted site values. Confirm with screenshot comparisons before locking tokens.

## Typography
- Use a licensed, readily available geometric/grotesk sans-serif such as `Manrope`, with `Inter` as a body alternative and system sans fallback.
- Hero: `clamp(3rem, 6vw, 5.5rem)`, weight 700–800, line-height 1.03–1.1, slight negative letter spacing.
- H1 interior page: `clamp(2.5rem, 4vw, 4.5rem)`, weight 700–800.
- H2: `clamp(2rem, 3vw, 3rem)`; H3: `1.4–1.8rem`.
- Body: 16–18px, line-height 1.6–1.75; technical prose width around 65–75 characters.
- Avoid tiny gray text; honor WCAG contrast requirements.

## Layout
- Desktop site container around 1200px, with fluid side padding `clamp(20px, 4vw, 64px)`.
- Hero: large expressive heading, brief supporting statement, restrained supporting diagrams/graphics.
- Navigation: simple rounded white bar with subtle dark outline, clear active state, responsive mobile menu.
- Section gaps: generally 80–128px desktop and 48–72px mobile.
- Use cards to organize concepts; avoid cardifying every paragraph.
- Prefer asymmetrical editorial compositions for marketing pages, regular readable grids for docs.

## Components
- `SiteHeader`: rounded white navigation, accessible keyboard states.
- `PrimaryButton`: high-contrast pill button; `SecondaryButton`: white pill with thin dark outline.
- `ConceptCard`: white surface, thin outline, 16–24px radius, generous internal padding, optional pastel accent.
- `SectionHeading`: strong title, compact introduction, optional eyebrow.
- `ProcessStep`: numbered stage with connectors; readable in vertical mobile view.
- `DiagramPanel`: neutral framed canvas with consistent typography and clear connectors.
- `Callout`: restrained accent tint, border, icon, clear semantic purpose.
- `ArticleLayout`: narrow reading column, headings with anchors, code blocks, tables, optional TOC.
- `CodeBlock`: accessible contrast, copy button, horizontal overflow handling, syntax highlighting.
- `Tabs`, `Accordion`: accessible and keyboard-operable; only use when information architecture warrants them.

## SHAPE-specific pages
- Home: strong value proposition; 5 SHAPE principles as a visual system; links into Organization, Process, Artifacts, Practitioner Guides.
- Philosophy: editorial narrative, concept callouts, few decorations.
- Organization: pod/team model diagrams and responsibility cards.
- Process: numbered, connected steps with inputs, outputs, review checkpoints.
- Artifacts / repository structure: file-tree visualizations, copyable examples, precise tables.
- Practitioner guides: documentation-first layout, TOC, code and examples; white/light surfaces dominate.

## Interaction and motion
- Use subtle 150–250ms transitions for hover/focus, gentle scroll reveals only where meaningful.
- Honor `prefers-reduced-motion`.
- Do not gate important content behind animations, hover, or carousels.
- Ensure mobile navigation, all links and controls, forms, and accordion elements have keyboard and touch support.

## Accessibility and responsiveness
- Aim at WCAG 2.2 AA contrast and interaction requirements.
- Responsive at common mobile, tablet, desktop widths; no horizontal scrolling.
- Maintain minimum comfortable 44x44px interactive targets where feasible.
- Distinguish headings semantically and maintain visible focus outlines.
- Test diagrams and wide technical tables on small screens.

## Implementation instructions for coding agent
1. Inspect the Meeko reference URL visually if browser access is available. Capture desktop and mobile screenshots of the homepage and representative interior pages; identify patterns, not source assets to reuse.
2. Implement design tokens centrally using CSS variables or the existing project's token mechanism. Do not hardcode one-off colors and spacing in page components.
3. Build a small library of reusable site components before expanding pages.
4. Implement the SHAPE content architecture rather than copying the portfolio template's page structure.
5. Compare the rendered homepage to the reference for overall feeling, spacing, typography, border treatments, and density. Refine design tokens and reusable components once.
6. Apply the same design system consistently to all new pages. Technical documentation should remain more restrained than the homepage.
7. Do not introduce third-party graphics, fonts, or illustrations without confirming license/usage rights.

## Acceptance criteria
- Recognizably inspired by the reference's light pastel editorial aesthetic, without being a clone.
- One global token source for color, type, radii, spacing and content widths.
- Distinct and consistent reusable cards, navigation, buttons, callouts and diagrams.
- Responsive on mobile, tablet and desktop; no layout overflows.
- Technical content is readable, navigable and copyable.
- Accessible keyboard focus, sufficient contrast and reduced-motion behavior.