# DESIGN.md — project starter

Reference: https://www.mortenagiraffe.com/design-blueprint
Reference reviewed: 2026-10-26
Status: draft for YOUR project; not an approved implementation plan.

## Ownership and evidence
- Replace this title with your project name and record the design owner.
- Reviewed reference: Morten A. Giraffe DESIGN.md and CSS tokens. This starter is an adaptation, not the full repository authority.
- Observed screenshot: public homepage, 1440 × 1000 viewport, captured 2026-10-26. It cannot prove unseen states.
- Inferred: suitability for your audience, product and content. Validate before adoption.
- Selected variant: signature / comfortable / editorial. Quiet mist, warm paper, compact density and square shapes are optional adaptations.
- Do not overwrite an existing DESIGN.md. Reconcile differences with its owner.

## Purpose and audience
Write the main user, their task, the content available and the primary action. List out-of-scope screens. Avoid unsupported claims, fake testimonials and placeholder proof.

## Colors
| Role | Value |
|---|---|
| Canvas | #f4f3ee |
| Text | #111111 |
| Dark surface | #171717 |
| Secondary text on light | #595952 |
| Action background | #e5ff00 |
Use ink on the action background. Text/action contrast: 16.76:1. This pair check is not a whole-page accessibility certification.

## Typography
Reference uses Space Grotesk and JetBrains Mono. Offline sample uses system-ui and ui-monospace; it does not download fonts. Confirm font rights and loading before changing a project. One H1; meaningful H2/H3 nesting; readable prose up to 65 characters; body line-height 1.65. Sample heading clamp 2.5–5rem. Preserve existing project type utilities where available.

## Spacing and layout
Selected gap: 24px. Use multiples of 8px for related spacing. Sample max-width: 72rem. Desktop two-column examples collapse below 640px. Use actual content to decide breakpoints, not a device list. Full-width editorial bands; framed panels only for real tools or examples; no nested decorative cards.

## Components and states
Control radius: 12px. Large panel radius: 24px.
Buttons need readable labels, at least 44px height, visible focus and clear disabled states. Forms require labels, validation, pending, success and recoverable failure states before shipping. The sample input is a demo with no backend. Use native disclosures for optional detail. Test long labels and empty/error content.

## Responsive behavior
Verify 375, 390, 768, 1024 and 1440px widths, zoom and text expansion. No clipped copy or page-level horizontal overflow. Preserve source order when columns collapse. Do not hide key information on mobile.

## Accessibility
Check every text/surface pair, keyboard sequence, focus visibility, landmarks and accessible names. Normal text target 4.5:1, large text 3:1; required UI boundaries/focus indicators 3:1. Do not encode meaning only in color. Announce asynchronous results accurately. Review with assistive technology; passing a contrast calculation is insufficient.

## Motion
Use motion only for feedback. Reference easing: cubic-bezier(0.22, 1, 0.36, 1). No animation is required in this starter. Respect reduced motion. Content must remain visible without animation or JavaScript.

## Imagery and content
Use owned or licensed imagery with truthful captions and useful alternatives. Screenshots must name capture date, viewport and source. A generated preview is not evidence of a shipped product. Do not reuse another person's identity or claims.

## Implementation and verification
Read PRD, architecture and system patterns first. Implement one representative route with existing dependencies. Compare before/after screenshots; test interactions and run repository checks. Record changed paths, exact checks, remaining gaps and rollback in progress.md. Obtain the required project release approval before deployment.