CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-09-09 14:38:59 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
tehran-v1
gstack/DESIGN.md
T
Garry TanandClaude Fable 5.1 982a738663 fix(design): Aside dump script stays single-quoted; redaction gate sized to the dump cap; doctrine made consistent 
- The DOM-dump Aside block was the only double-quoted `aside repl` script in
  the tree (to splice the function text), which put the agent-filled <url>
  inside a double-quoted bash string: a same-origin href carrying $(...) would
  run in the reviewer's shell when Phase 3 opened that page. The script is
  single-quoted like every other Aside script and the function text enters
  through a closed-quote segment ('"$_DUMP"'); the fallback line is
  `$B js '('"$_DUMP"')()'`. A free test pins that no rendered Aside script
  opens with a double quote.
- The persist block capped dumps at 10 MiB but ran gstack-redact with its
  1 MiB default, so every real page between the two was deleted as
  DOM_DUMP_REDACTION_BLOCKED; the gate passes --max-bytes at the dump cap and
  blocks on any exit other than clean (0) or MEDIUM (2), so a redaction tool
  that fails to run can no longer fall through to "persist".
- Dump hygiene removes <template> and <noscript> subtrees (invisible to the
  attribute walk), inline on* handlers, and the cross-origin <link> nodes
  already named in the note, so the file handed to the engine references no
  remote stylesheet.
- Doctrine: the Codex design-voice prompts said "2-3 intentional motions"
  against the one-authored-moment rule; the overused-display heading scoped
  its ban to Persuade/Experience while the catalog and hard rules ban it
  everywhere; design-consultation's Important Rule 4 still said "as primary";
  design-html's blacklist header is now "Never include by default" with the
  mockup/DESIGN.md/user-ask override the catalog grants; the slop gate honors
  Decisions Log and Do's and Don'ts blessings like /review does; the landing
  "poster" line says poster in stance, not type size; the design binary's
  variant dials no longer flip light/dark for variety; gstack's DESIGN.md
  rows name data labels (UI labels stay the DM Sans token) and call the
  skill-bar fill and hovers functional transitions.
- design-review names how the base branch is found (gh pr view, then the
  repo default; never main) for the source-mode scan and the diff-aware mode.
- frontend-scope matches the config globs at the repo root only, like the
  bash arm; the parity test carries nested samples.
- Cleanups: renderCatalog's stale style option, an unused import, the
  identity-map bannedFontNames, the checklist header's "same entries" claim,
  the catalog header's consumer list, the orphaned main() docstring, the
  plan doc's IIFE bullet. design-html's skeleton ceiling is re-measured
  (54,184) for the two doctrine sentences.

Tests: AUTO-FIX rendering from the catalog, the E2E slice markers checked in
the free suite, the hygiene cases for templates/noscript/handlers/remote
links, and the review E2E counting detector rows separately from the seven
checklist plants.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-08 18:05:21 +00:00

144 lines
6.1 KiB
Markdown
Raw Permalink Blame History

---
# gstack: design-md-format=spec
name: gstack
typography:
display:
fontFamily: Satoshi
body:
fontFamily: DM Sans
label:
fontFamily: DM Sans
mono:
fontFamily: JetBrains Mono
fontFeature: tnum
colors:
primary-dark-mode: "#F59E0B"
primary-light-mode: "#D97706"
primary-text-accent-dark-mode: "#FBBF24"
primary-text-accent-light-mode: "#B45309"
zinc-50: "#FAFAFA"
zinc-400: "#A1A1AA"
zinc-600: "#52525B"
zinc-800: "#27272A"
surface-dark: "#141414"
base-dark: "#0C0C0C"
surface-light: "#FFFFFF"
base-light: "#FAFAF9"
border-dark: "#262626"
border-light: "#E7E5E4"
success: "#22C55E"
warning: "#F59E0B"
error: "#EF4444"
info: "#3B82F6"
spacing:
2xs: 2px
xs: 4px
sm: 8px
md: 16px
lg: 24px
xl: 32px
2xl: 48px
3xl: 64px
rounded:
sm: 4px
md: 8px
lg: 12px
full: 9999px
---
# Design System — gstack
## Overview
- **What this is:** Community website for gstack — a CLI tool that turns Claude Code into a virtual engineering team
- **Who it's for:** Developers discovering gstack, existing community members
- **Space/industry:** Developer tools (peers: Linear, Raycast, Warp, Zed)
- **Project type:** Community dashboard + marketing site
- **Direction:** Industrial/Utilitarian — function-first, data-dense, monospace as personality font
- **Decoration level:** Intentional — subtle noise/grain texture on surfaces for materiality
- **Mood:** Serious tool built by someone who cares about craft. Warm, not cold. The CLI heritage IS the brand.
- **Reference sites:** formulae.brew.sh (competitor, but ours is live and interactive), Linear (dark + restrained), Warp (warm accents)
## Colors
- **Approach:** Restrained — amber accent is rare and meaningful. Dashboard data gets the color; chrome stays neutral.
- **Primary (dark mode):** amber-500 #F59E0B — warm, energetic, reads as "terminal cursor"
- **Primary (light mode):** amber-600 #D97706 — darker for contrast against white backgrounds
- **Primary text accent (dark mode):** amber-400 #FBBF24
- **Primary text accent (light mode):** amber-700 #B45309
- **Neutrals:** Cool zinc grays
- zinc-50: #FAFAFA (lightest)
- zinc-400: #A1A1AA
- zinc-600: #52525B
- zinc-800: #27272A
- Surface (dark): #141414
- Base (dark): #0C0C0C
- Surface (light): #FFFFFF
- Base (light): #FAFAF9
- **Semantic:** success #22C55E, warning #F59E0B, error #EF4444, info #3B82F6
- **Dark mode:** Default. Near-black base (#0C0C0C), surface cards at #141414, borders at #262626.
- **Light mode:** Warm stone base (#FAFAF9), white surface cards, stone borders (#E7E5E4). Amber accent shifts to amber-600 for contrast.
## Typography
- **Display/Hero:** Satoshi (Black 900 / Bold 700) — geometric with warmth, distinctive letterforms (the lowercase 'a' and 'g'). Not Inter, not Geist. Loaded from Fontshare CDN.
- **Body:** DM Sans (Regular 400 / Medium 500 / Semibold 600) — clean, readable, slightly friendlier than geometric display. Loaded from Google Fonts.
- **UI/Labels:** DM Sans (same as body)
- **Data/Tables:** JetBrains Mono (Regular 400 / Medium 500) — the personality font. Supports tabular-nums. Monospace should be prominent, not hidden in code blocks. Loaded from Google Fonts.
- **Code:** JetBrains Mono
- **Loading:** Google Fonts for DM Sans + JetBrains Mono, Fontshare for Satoshi. Use `display=swap`.
- **Scale:**
- Hero: 72px / clamp(40px, 6vw, 72px)
- H1: 48px
- H2: 32px
- H3: 24px
- H4: 18px
- Body: 16px
- Small: 14px
- Caption: 13px
- Micro: 12px
- Nano: 11px (JetBrains Mono labels)
## Layout
- **Approach:** Grid-disciplined for dashboard, editorial hero for landing page
- **Grid:** 12 columns at lg+, 1 column at mobile
- **Max content width:** 1200px (6xl)
- **Border radius:** sm:4px, md:8px, lg:12px, full:9999px
- Cards/panels: lg (12px)
- Buttons/inputs: md (8px)
- Badges/pills: full (9999px)
- Skill bars: sm (4px)
### Spacing
- **Base unit:** 4px
- **Density:** Comfortable — not cramped (not Bloomberg Terminal), not spacious (not a marketing site)
- **Scale:** 2xs(2px) xs(4px) sm(8px) md(16px) lg(24px) xl(32px) 2xl(48px) 3xl(64px)
## Motion
- **Approach:** Minimal-functional — only transitions that aid comprehension. The dashboard's live feed IS the motion.
- **Easing:** enter(ease-out / cubic-bezier(0.16,1,0.3,1)) exit(ease-in) move(ease-in-out)
- **Duration:** micro(50-100ms) short(150ms) medium(250ms) long(400ms)
- **Animated elements:** live feed dot pulse (2s infinite), skill bar fill (600ms ease-out), hover states (150ms)
## Grain Texture
Apply a subtle noise overlay to the entire page for materiality:
- Dark mode: opacity 0.03
- Light mode: opacity 0.02
- Use SVG feTurbulence filter as a CSS background-image on body::after
- pointer-events: none, position: fixed, z-index: 9999
## Decisions Log
| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-21 | Initial design system | Created by /design-consultation. Industrial aesthetic, warm amber accent, Satoshi + DM Sans + JetBrains Mono. |
| 2026-03-21 | Light mode amber-600 | amber-500 too bright/washed against white; amber-700 too brown/umber. amber-600 is the sweet spot. |
| 2026-03-21 | Grain texture | Adds materiality to flat dark surfaces. Prevents the "generic SaaS template" sameness. |
| 2026-09-08 | Open DESIGN.md format | Converted with `gstack-design-md convert`: tokens in front matter, canonical sections, Motion and Decisions Log kept as extras. DM Sans stays the body face: it sits on the overused-as-display list, and body/UI use on an Operate surface is the allowed exception under the role-scoped rule. |
| 2026-09-08 | Live-feed pulse is the one authored motion moment | The 2s pulse on the live-feed dot is the one authored motion moment, an intentional exception to the pulsing-dot catalog rule. The skill-bar fill and the 150ms hover transitions are functional state transitions, not authored moments. |
| 2026-09-08 | JetBrains Mono data labels at 11px | Data labels at Nano (11px) run in JetBrains Mono, below the 12px UI-text floor; UI labels stay DM Sans (the `typography.label` token). Recorded so the detector's undersized-ui-text and monospace-costume rows are read as decided, not open. |
Reference in New Issue View Git Blame Copy Permalink