Design Guide

Chips’nCode Design System

A living design-language spec for a multi-mode website: one visual grammar, many page archetypes, zero tolerance for generic template cloning.

system://status

updated: 2026-03-08
site modes: 7
header modes: 2
interaction rule: enhance, never block

Archive: previous working version is preserved as Design Language Archive - 2026-03-08.

1) North Star Principles

Cohesive, not uniform

Every section should feel related. No section should feel copy-pasted.

Scanning first, depth second

Indexes optimize orientation. Detail pages optimize comprehension.

Frame follows content

Header strength (plain vs panel) should match content behavior, not fashion.

Enhance, never gate

Interactive layers are optional. Core reading/navigation always works without them.

Bad rule

One template for every page.

Better rule

One voice, section-specific pacing.

Actual rule

Shared primitives + archetype-aware composition.

2) Documentation References

Structure inspiration for this page and this system was taken from mature design docs patterns:

Atlassian Design System Foundations: clear split between foundations, guidelines, and styles.
Atlassian Design Tokens: semantic naming and token governance model.
Radix Primitives Introduction: accessibility-first component philosophy.
Radix Accessibility Overview: explicit focus/keyboard/aria contract.
IBM Carbon: foundation + pattern + governance framing.
Primer Foundations: practical, implementation-oriented foundations docs.

Important: this page is inspired by documentation architecture, not visual identity. Chips’nCode keeps its own visual language.

3) Foundations

3.1 Site topology

/                        switchboard
/notebook                editorial index
/projects                build index
/tools                   utility index
/docs                    manual index
/education               teaching index
/astrophotography        image-led index
/poetry                  literary archive
/tags/[tag]              cross-collection relationship index

3.2 Foundation stack

Type and voice

technical but human
concise metadata, generous prose
clear heading hierarchy

Surface language

panel and panel—soft as primary grouping surfaces
borders carry structure; shadows are secondary
gradients used to signal section character

Interaction model

link-first navigation baseline
optional query drawers for power users
keyboard and focus contracts are mandatory

3.3 Theme contract

Rule	Current behavior	Why
Global default	Light-first with toggle	broad readability baseline
Persisted choice	stored in `localStorage`	continuity across visits
Astrophotography exception	forced dark mode	image contrast and section intent
System preference fallback	used when no explicit selection	user-respectful default

3.4 Header decision matrix

Context	Use	Expected result
text-first longform	`headerStyle: plain`	reduced chrome, reading priority
artifact/build/demo lead	`headerStyle: panel`	stronger metadata + media framing
panel without hero media	panel text-only fallback	stable visual rhythm
education clarity-sensitive page	plain or low-noise panel	cognitive load control

3.5 Architecture Diagrams

System path map

Home (/)
  -> section indexes
      -> /notebook
      -> /projects
      -> /tools
      -> /docs
      -> /education
      -> /astrophotography
      -> /poetry
  -> detail pages ([slug] routes)
  -> relationship layer (/tags/[tag])

Interaction stack

[L3] Optional query layer     edge drawers + CLI shell
[L2] Enhanced browse layer    sorting + related tags + quick panels
[L1] Core navigation layer    links + lists + heading hierarchy
[L0] Content baseline         semantic HTML + readable prose

Theme resolution flow

Route = /astrophotography ?  yes -> force dark mode
                              no -> check saved theme
                                         -> if missing, use system preference

L0-L3: layered interaction modelforce dark mode: route-level exception, not user toggle failure

4) Archetypes by Section

Switchboard

Homepage

Signature: migration banner + thematic routing chips + mixed masonry signal.

cross-collection highlights
high-level route affordances
latest-entry pull-through

Editorial

Notebook

Signature: lead story + support rail + dense archive.

featured semantics
date/tag readable at scan speed
optional query drawer

Artifact

Projects

Signature: featured build + archive grid + detail pages with flexible hero framing.

strong metadata strips
spec/status/journal content blocks
project detail pages can be plain or panel

Utility

Tools

Signature: lead utility + compact deck + function-forward metadata.

quick-identification glyphing
short descriptions with high information density
optional query drawer

Manual

Docs

Signature: quick panels + directory grouped by section.

start-here path
latest + popular tags visibility
query drawer with man-page behavior

Teaching

Education

Signature: teaching shelf layout with taxonomy-first metadata.

subject/level/type pills
featured + support + archive flow
legacy route compatibility where required

Relationship

Tag Pages

Signature: cross-collection archive with sorting and related-tag context.

collection mix strip
related tags module
client-side sort controls

Image / Literary

Astro + Poetry

Signature: pace-sensitive sections with reduced chrome and stronger mood control.

astro dark-mode lock
poetry archival cadence
minimal UI noise in reading zones

5) Shared Pattern Library (Operational)

5.1 Reuse-first primitives

Primitive	Intent	Anti-pattern
`Header`	global orientation, route access, theme control	per-section nav forks with divergent behavior
`IndexHeader`	section identity + status framing	bespoke hero wrappers per index
`panel` / `panel--soft`	content grouping and visual rhythm	custom one-off card wrappers
`pill` / `pill--link`	compact metadata and taxonomy	ad-hoc tag styling across sections
`edge-drawer-*`	optional side-utilities	modal-only query tools that block reading
`CliShell`	command-style discovery for dense indexes	shell UX without link-based fallback

5.2 Drawer pattern contract

Do

keep drawer optional
include close/backdrop affordances
hide query overlays on constrained mobile breakpoints
keep equivalent content discoverable through page structure

Do not

hide critical navigation inside drawers
require shell commands for core discovery
ship keyboard-inaccessible overlays
duplicate taxonomy logic between drawer and page with mismatch

5.3 Metadata and taxonomy contract

Tags must be meaningful across collections, not collection-local aliases.
featured marks editorial priority, not simply recency.
Date signals should consistently resolve from updatedDate then pubDate where applicable.
Taxonomy pills in education should map to tag routes only when actual tag data exists.

5.4 Pattern Specimens (Before and After)

Index Header Pattern

Before

single generic heading block
no section-specific status framing
weak scan affordance above fold

After

IndexHeader with eyebrow + lede + optional status lines
immediate section identity and purpose
consistent entry frame across index archetypes

Discovery Pattern

Before

single browse path only
dense indexes become hard to query
no power-user interaction layer

After

optional edge-drawer query layer
CLI-style search remains additive
core link-based browsing always intact

Detail Hero Pattern

Before

single hero treatment for all detail pages
media-first layout forced on text-first entries
inconsistent reading rhythm

After

headerStyle controlled per entry
plain and panel map to content behavior
stable fallback when hero media is absent

5.5 Component Anatomy

Global Header Anatomy

Brand anchor: stable home return point.
Primary route rail: section-level navigation.
Theme control: explicit user preference override.
Utility link: source / external utility access.
Sticky frame: persistent orientation while scrolling.

Index Card Anatomy

Kicker/meta: type, featured state, date.
Primary title: strongest click target.
Description: one-paragraph scan summary.
Tag row: relationship routing to related content.
Media slot: optional visual context, never required for function.

Edge Drawer Anatomy

Tab handle: discoverable but low-noise trigger.
Backdrop: explicit close affordance.
Panel shell: isolated utility context.
Query engine: filter/open behavior on indexed content.
Manual layer: command help without leaving current page.

6) Accessibility and Quality Gates

Gate	Minimum requirement	Ship decision
Semantic structure	single `h1`, logical heading tree, landmark clarity	block if violated
Keyboard flow	all interactive controls reachable and operable by keyboard	block if violated
Focus visibility	focus indicator visible against all surfaces	block if violated
Color semantics	state/meaning not encoded by color alone	block if violated
No-JS resilience	core browse/read path still works without client scripts	block if violated
Responsive integrity	no clipped content or unusable controls at narrow viewport widths	block if violated

6.1 Pre-merge design QA

Archetype identified and respected.
Existing primitive reused where possible.
Theme behavior verified on both light and dark modes.
Route-specific theme exceptions verified (astrophotography).
Keyboard and screen-reader basic pass completed.
Mobile breakpoint pass completed.
Spec updated if behavior changed materially.

7) Governance, Versioning, and Change Control

Spec status

This page is the active design-system specification for Chips’nCode.

Archive policy

Before major rewrites, duplicate active spec to a dated archive and cross-link both versions.

7.1 Required process for major design updates

Create archive snapshot: site-architecture-and-design-language-archive-YYYY-MM-DD.mdx.
Add archive link callout at top of active spec.
Update the history section with concrete date and scope.
Confirm route build succeeds for both active and archive pages.

7.2 Planned improvements

formal token registry page for --space-*, surface, and semantic color usage
explicit motion guidelines per interaction type
component-level accessibility checklists by primitive
screenshot-backed examples for each archetype pattern

8) History

2026-03-01

Initial Architecture Spec

The first design-language page established the multi-section model and the core rule: cohesive design language over cloned templates.

2026-03-02

Archetype Refinement

Section-level archetypes were clarified, including index behavior, header modes, and early route-specific pacing rules.

2026-03-08

System Alignment Pass

Documentation was aligned to live behavior: edge query drawers, theme contracts, taxonomy interactions, and cross-collection relationships.

2026-03-08 (rev B)

Documentation Design Upgrade

The spec became a richer public design document with architecture diagrams, before/after specimens, and component anatomy maps.