Skip to main content

Style guide

The tokens, components, and patterns behind this site, with live examples, props, and usage rules.

A JSON version of this guide is available for coding agents. Open system.json

Color tokens

The palette has cool paper, charcoal ink, and one denim accent. Values and descriptions are read from design-system/tokens.json at build time.

  • paper

    #FAFBFC

    CSS
    var(--paper)
    Tailwind
    paper
    On paper
    1.0:1, surfaces and decoration

    Page background. Near-white with a faint cool cast.

  • raised

    #FFFFFF

    CSS
    var(--raised)
    Tailwind
    raised
    On paper
    1.0:1, surfaces and decoration

    Raised surfaces that lift off paper. Use sparingly. Too many white cards on paper make a page look generated (see rules.json guidelines).

  • surface-warm

    #F7F5F0

    CSS
    var(--surface-warm)
    Tailwind
    surface-warm
    On paper
    1.1:1, surfaces and decoration

    Warm tint for small inline callouts only, such as the blog author card. Do not use it as a full-width section background.

  • ink

    #1A1B1E

    CSS
    var(--ink)
    Tailwind
    ink
    On paper
    16.6:1, text on paper

    Primary text and dark (ink) surfaces.

  • ink-soft

    #292A2E

    Tailwind
    ink.soft
    On paper
    13.8:1, text on paper

    Slightly lifted ink for layered dark surfaces.

  • ink-muted

    #565760

    CSS
    var(--ink-muted)
    Tailwind
    ink.muted
    On paper
    6.9:1, text on paper

    Secondary text. It is 6.9:1 on paper, so it passes AA.

  • ink-faint

    #9A9AA1

    CSS
    var(--ink-faint)
    Tailwind
    ink.faint
    On paper
    2.7:1, surfaces and decoration

    Decoration only, such as separator dots, arrow glyphs, and empty-state rings. At 2.7:1 it can't carry readable text at any size. Use ink-muted for anything a reader has to read.

  • line

    #E5E7EB

    CSS
    var(--line)
    Tailwind
    line
    On paper
    1.2:1, surfaces and decoration

    Hairline rules and borders.

  • line-strong

    #D4D7DD

    CSS
    var(--line-strong)
    Tailwind
    line.strong
    On paper
    1.4:1, surfaces and decoration

    Emphasized rules and input borders.

  • accent

    #2E5C8A

    CSS
    var(--accent)
    Tailwind
    accent
    On paper
    6.7:1, text on paper

    The single accent: deep denim navy on light surfaces (6.7:1). It follows the surface: site.css swaps --accent-rgb to accent-on-ink inside .bg-ink / [data-surface='dark']. Always reference it as `accent` / var(--accent), never as a literal, or it won't follow the surface.

  • accent-on-ink

    #6BA6D8

    On paper
    2.5:1, surfaces and decoration

    Accent value on dark ink surfaces (6.6:1). The surface rules in site.css apply it automatically. Do not select it directly.

  • accent-pressed

    #234A70

    Tailwind
    accent.ink
    On paper
    8.9:1, text on paper

    Pressed and darker accent on light surfaces.

Dark theme

Dark theme values. site.css applies them on screen under :root[data-theme='dark'] by reassigning the light custom properties (--paper, --ink, ...), so components keep using the same tokens. Inside ink and denim bands --ink and --paper swap, so bands take the page colour and hairlines mark their edges instead of a fill. Print always uses the light values. Use the theme switch in the header to see this page in dark.

  • dark.paper

    #0F1012

    Dark page background (--paper, --dark-bg). Ink bands blend into it.

  • dark.raised

    #17181B

    Dark raised surface (--raised).

  • dark.surface-warm

    #1C1B18

    Dark warm callout tint (--surface-warm). Callouts only, as in light.

  • dark.ink

    #ECEEF1

    Dark-theme text (--ink, --dark-fg).

  • dark.ink-muted

    #A0A3AB

    Dark-theme secondary text (--ink-muted). AA on dark paper and raised.

  • dark.ink-faint

    #5C5F66

    Dark-theme decoration only (--ink-faint). Never text.

  • dark.line

    #26282C

    Dark-theme hairline (--line). Also marks where a band starts and ends.

  • dark.line-strong

    #34373C

    Dark-theme emphasized hairline (--line-strong).

  • dark.action

    #386C9F

    Primary action fill in dark (--action-dark). White text 5.5:1; 3.4:1 against dark paper so the block reads as a control.

  • dark.action-hover

    #2E5C8A

    Primary action hover in dark (--action-dark-hover): deepens on hover, as in light.

Page-family values

Defined in redesign.css for the portfolio pages. These values are not in tokens.json. Use the tokens above in new work.

  • --portfolio-blue

    #244C71

    Primary actions, editorial italics, and feature bands. It is close to accent. Use accent in new work.

  • --portfolio-tint

    #EDF1F4

    Tool workspaces, related content, and example stages.

Surfaces

Paper & ink

Primary text stays dark. Descriptions use muted ink. Readable text never uses faint ink.

Browse writing

Denim & paper

Feature bands use white text and lighter blue supporting text. Keep links underlined.

Read recommendations

Ink & paper

The footer, project navigation, and code use light text on ink. The accent brightens automatically on this surface.

Get in touch

Type and hierarchy

The site uses four font families, each for one role. Headings are bold sans. The serif italic marks one phrase in a page title. Section headings stay plain.

  • Body, interface, and headings.

    Hanken Grotesk

    Body text, UI, and headings.

    var(--font-hanken)
  • Display headlines and italics.

    Newsreader

    Display serif for headlines, oversized numerals, and the editorial italic. Do not use it for small functional text. The CSS var keeps its historic name.

    var(--font-fraunces)
  • const shared = true;

    Geist Mono

    Technical text and metadata, such as labels, code, and indices.

    var(--font-geist-mono)
  • Style Script

    Signature wordmark only. It has one weight and no tabular figures. It is unreadable below about 20px.

    var(--font-script)

Type scale

  1. .page-type

    Page title

  2. .section-type

    Section heading

  3. <Heading visual="h2">

    Subsection heading

  4. .page-lede

    A one- or two-sentence introduction to the page.

  5. <Text size="lg" tone="muted">

    Explain the situation, the alternatives, and the reason for a decision.

  6. <Text size="sm" tone="muted">

    Captions describe what the reader is seeing.

Pages open two ways. .page-opener sets the big title for pages that introduce something: home, listings, case studies, articles. .page-opener--document sets a plain title for the résumé, contact, and legal pages.

<Heading>

Renders every heading. level sets the tag and visual sets the size. The visual size never changes the document outline.

src/components/primitives/Heading.astro See it in use

Props

PropTypeDefaultDescription
levelRequired 1 | 2 | 3 | 4 | 5 | 6 None None
visual 'display-xl' | 'display-lg' | 'display-md' | 'h1' | 'h2' | 'h3' | 'h4' | 'eyebrow' None None
tone 'ink' | 'paper' | 'accent' | 'muted' 'ink' Deprecated: navy → ink, plum → ink, white → paper, coral → accent.
align 'left' | 'center' 'left' None
class string None None
id string None None

Do

  • Pick level from the outline and visual from the design.
  • Set page titles in one typeface, with no serif-italic phrase and no colored end mark.

Don’t

  • Skip heading levels to get a smaller size.
  • Use tone="faint" or deprecated tones such as navy and coral.
View markup
Example.astro astro
<Heading level={2} visual="h2">Subsection heading</Heading>
<Text size="lg" tone="muted">Explain the situation and the reason.</Text>

<Text>

Body copy on the type scale for case studies and supporting pages.

src/components/primitives/Text.astro See it in use

Props

PropTypeDefaultDescription
size 'xs' | 'sm' | 'base' | 'lg' | 'xl' 'base' None
tone 'ink' | 'muted' | 'paper' | 'whiteMuted' | 'faint' | 'accent' 'ink' Deprecated: navy → ink, white → paper, coral → accent.
weight 'normal' | 'medium' | 'semibold' 'normal' None
align 'left' | 'center' 'left' None
as 'p' | 'span' | 'div' 'p' None
leading 'tight' | 'snug' | 'normal' | 'relaxed' 'relaxed' None
class string None None

Do

  • Use tone="muted" for descriptions and captions.

Don’t

  • Use tone="faint" for words a reader needs. It is for glyphs and separators only.

Accessibility

  • Muted ink is 6.9:1 on paper. Faint ink is 2.7:1 and fails for text at any size.

Layout and spacing

Pages use four content widths and three spacing steps.

Container widths

  • width="narrow" 48rem

    Supporting copy and narrow page content

  • width="content" 64rem

    Case-study reading layouts

  • width="default" 72rem

    General page content

  • width="wide" 80rem

    Main page grids and full design sheets

Spacing

  • var(--space-section)

    clamp(6rem, 4rem + 7.5vw, 11rem)

  • var(--space-block)

    clamp(3.5rem, 2.4rem + 4.5vw, 6.5rem)

  • var(--space-item)

    clamp(2.75rem, 2rem + 2.8vw, 4.5rem)

Section padding uses --space-section, heading-to-content gaps use --space-block, and gaps between items use --space-item. All three scale fluidly between phone and desktop.

<Container>

Caps content width and adds a 24px gutter on each side. The width caps include the gutters.

src/components/layout/Container.astro See it in use

Props

PropTypeDefaultDescription
width 'narrow' | 'content' | 'default' | 'wide' 'default' None
as 'div' | 'section' | 'article' | 'main' | 'header' | 'footer' | 'nav' 'div' None
class string None None

Don’t

  • Put case-study artwork inside .case-layout. Use a sibling <Container width="wide"> instead.

<Section>

A full-width page band that sets the surface. The accent follows the surface automatically.

src/components/layout/Section.astro See it in use

Props

PropTypeDefaultDescription
tone 'paper' | 'ink' | 'raised' 'paper' Deprecated: cream → paper, white → raised, navy → ink, plum → ink, charcoal → ink. Not allowed: surface-warm.
padding 'tight' | 'default' | 'loose' 'default' None
id string None None
class string None None
decorated boolean false Apply `relative overflow-hidden` so absolutely-positioned blobs clip safely.

Don’t

  • Use surface-warm as a section tone. It is for small inline callouts only.

Motion

Motion explains a change of state or makes an available action easier to notice. It stops when reduced motion is requested.

  • var(--ease-out)

    cubic-bezier(0.22, 1, 0.36, 1)

    Default easing for entrances and state changes.

  • var(--ease-inout)

    cubic-bezier(0.65, 0, 0.35, 1)

    Movement between two resting states.

Durations

  • 200ms

    Link arrows nudge 3px toward where they point, on hover and keyboard focus.

  • 320ms

    Page content fades in on navigation.

  • 700ms

    Hero content rises 12px with a small stagger between lines.

Sample headingSupporting line that enters after the heading.

Actions and links

A filled denim action for the next important step, and an underlined editorial link for the supporting route.

<Icon>

Phosphor icons through Iconify, decorative unless given a label.

src/components/primitives/Icon.astro See it in use
Keyboard access

Props

PropTypeDefaultDescription
nameRequired string None Iconify name, e.g. "ph:arrow-right" or "ph:check-circle-duotone".
size number 24 Pixel size for width/height. Defaults to 24.
label string None Accessible label. If omitted, icon is treated as decorative.
class string None Tailwind text-* color class controlling stroke/fill.

Accessibility

  • Without a label, the icon is hidden from assistive technology.
  • A standalone icon control needs a label.

Forms and feedback

Forms use visible labels, useful hints, specific errors, and a sending state. The contact page uses the same components.

<Field>

Wraps a control with its label, hint, required marker, and error, and wires the ids between them.

src/components/form/Field.astro See it in use

Use an address like you@example.com.

Two or three sentences.

Submit the form to see validation and the sending state. Nothing is sent.

Props

PropTypeDefaultDescription
labelRequired string None None
nameRequired string None None
id string `field-${name}` Stable id. Generated from name if omitted.
required boolean false None
hint string None None
error string None None
hideLabel boolean false Visually hide the label (still announced).
class string None None

Do

  • Put the label above the control. The error appears as a speech bubble right under it, above the hint.
  • Write errors that say how to fix the value without blaming the reader.

Don’t

  • Use a placeholder as the label.

Accessibility

  • Hint and error are joined to the control with aria-describedby.
  • Invalid fields get aria-invalid. On submit, focus moves to the first one.
  • The bubble pops in and the control shakes once, unless the reader prefers reduced motion.
View markup
Contact field pattern astro
<Field label="Email" name="email" required hint="Only used to reply.">
  <Input name="email" type="email" required
    describedBy="field-email-hint" />
</Field>
<SubmitButton label="Send message" loadingLabel="Sending…" />

<Input>

Single-line text, email, phone, and URL input. Its name must match the parent Field.

src/components/form/Input.astro See it in use

Enter a complete email address.

Props

PropTypeDefaultDescription
nameRequired string None Must match the parent <Field name>.
id string None Override. Defaults to `field-{name}` to match Field's auto id.
type 'text' | 'email' | 'tel' | 'url' | 'number' | 'password' | 'search' 'text' None
placeholder string None None
value string None None
required boolean false None
invalid boolean false Set by the consumer (Field) when an error is shown.
describedBy string None Comma-joined ids of hint/error elements.
autocomplete string None None
inputmode 'text' | 'numeric' | 'tel' | 'email' | 'url' | 'search' None None
class string None None

Accessibility

  • Set invalid and describedBy to match the Field so the error is announced.

<Textarea>

Multiline input with the same label and description wiring as Input. See it in the Field example above.

src/components/form/Textarea.astro See it in use

Props

PropTypeDefaultDescription
nameRequired string None None
id string None None
placeholder string None None
value string None None
rows number 5 None
required boolean false None
invalid boolean false None
describedBy string None None
class string None None

<SubmitButton>

The form's primary action, with ready, busy, and disabled states.

src/components/form/SubmitButton.astro See it in use

Props

PropTypeDefaultDescription
labelRequired string None None
disabled boolean false Also used for the server-rendered disabled and busy examples.
busy boolean false None
loadingLabel string 'Sending…' None
iconLeft string None None
iconRight string None None
size 'md' | 'lg' 'lg' None
class string None None
id string None None
form string None None

Accessibility

  • Busy swaps the label, shows a spinner, sets aria-busy, and blocks repeat submission.
  • Disabled keeps its label and lowers opacity.

<FormAlert>

Form-level feedback after submission. Hidden until the handler shows it.

src/components/form/FormAlert.astro See it in use

Message sent.

Props

PropTypeDefaultDescription
variantRequired 'success' | 'error' None None
hidden boolean true Hidden by default. Set to false to show it on first render.
id string None None
class string None None

Accessibility

  • Success is a polite status. Error is an assertive alert.

Content patterns

These patterns appear in case studies, articles, and recommendations.

<Metric>

A measured result with a label and supporting context.

src/components/patterns/Metric.astro See it in use
75%

fewer support calls

55%

fewer shipping errors

Props

PropTypeDefaultDescription
valueRequired string None None
labelRequired string None None
caption string None None
before string None Optional "before" value, struck through ahead of an arrow.
trend 'up' | 'down' None None
class string None None

Do

  • Keep the source, scope, and explanation close to the number.

Don’t

  • Show a figure that the project owner hasn’t confirmed.

<Tldr>

A case-study summary that expands into the problem, decision, and evidence.

src/components/patterns/Tldr.astro See it in use

Project summary

Interviews with the owner, COO, and office manager showed that the hardest part was getting the patient, two clinics, a courier, and IVFCRYO confirmed and ready before a shipment could start.

The decision
I chose one shared record over two separate apps, so patients and staff always see the same status.
The result
Support calls dropped 75% and shipping errors 55% once patients could see that both clinics had signed off.

Props

PropTypeDefaultDescription
situation string None None
problemRequired string None None
decisionRequired string None None
evidenceRequired string None None
class string None None

<Plate>

A full design sheet at its natural aspect ratio, with a caption and a zoom viewer.

src/components/patterns/Plate.astro See it in use
IVFCRYO shipment detail design sheet, showing readiness, shipment status, and tracking
Shipment detail

The shipment detail screen from the IVFCRYO case study.

Props

PropTypeDefaultDescription
srcRequired ImageMetadata None The sheet, imported so Astro can process it.
altRequired string None Real description of the sheet, for screen readers.
titleRequired string None Screen name, e.g. "Shipment detail".
index string None Optional plate index, e.g. "05" — renders a "Plate / 05" tag above.
caption string None Optional note under the caption rail.
size 'band' | 'half' 'band' `band` fills a wide container. `half` fills a two-up grid cell.
zoom boolean true Set false to omit the lightbox wiring entirely.
class string None None

Do

  • Place plates in a sibling wide Container, next to the text that uses them.

Accessibility

  • The viewer closes on Escape and returns focus to the trigger.

<Recommendation>

A named, attributed quote. The testimonials page also uses a larger featured layout on denim.

src/components/patterns/Recommendation.astro See it in use

Josh was always a great design and research partner… He always worked hard to ensure accessibility across our experience.

Drew DiPasquale

Principal Researcher

HubSpot

Props

PropTypeDefaultDescription
testimonialRequired CollectionEntry<'testimonials'> None None
featured boolean false None

Don’t

  • Edit or invent quotes. Quotes come from the person quoted.

<ArticleTable>

Wraps any table in a labeled, keyboard-scrollable region that keeps its column headings.

src/components/writing/ArticleTable.astro
PatternPurposeWhere it appears
Contents navigationJump between sections and track reading positionBlog articles
Expandable summaryRead the decision record without lengthening the openingProject pages

Accessibility

  • Scrolls sideways on phones instead of dropping headers.

.article-pager

Older and newer links at the end of each article.

Classes

  • article-pager

    The nav wrapper. Give it an aria-label.

  • article-pager-link

    One direction. Add article-pager-link--newer for the right-hand link.

  • article-pager-label / article-pager-title

    Small direction label, then the title, which turns accent on hover.

Do

  • Point arrows the way the reader travels: left for older, right for newer.
View markup
Article pager astro
<nav class="article-pager" aria-label="More articles">
  <a class="article-pager-link" href="/blog/older/">
    <span class="article-pager-label">Older article</span>
    <span class="article-pager-title">Older title</span>
  </a>
  <a class="article-pager-link article-pager-link--newer" href="/blog/newer/">…</a>
</nav>

<CodeBlock>

Highlighted code with line numbers and a copy action. Renders fenced code in posts and tool essays.

src/components/patterns/CodeBlock.astro
example.ts ts
const shared = true;
// A comment line.

Props

PropTypeDefaultDescription
codeRequired string None The code. Passed as a prop (not a slot) so it can be copied verbatim.
filename string None Filename shown in the header, e.g. "Modal.tsx".
lang ComponentProps<typeof Code>['lang'] None Language label, e.g. "tsx", "ts", "bash".
caption string None Caption rendered under the artifact in muted text.
copy boolean true Show the copy-to-clipboard button (default true).
class string None None

Accessibility

  • Copy announces success or failure.
  • Comment colors meet contrast on the dark theme.

Component index

The site’s pages use 75 components. Each one links to a page that shows it in use. npm run audit:components checks this list against the pages.

75 components

Site navigation7
  • Analytics

    The site analytics snippet in the document head.

    src/components/chrome/Analytics.astro
    See in use
  • DesktopNav

    Desktop primary navigation: Work and About disclosure panels on one shared surface that resizes between them.

    src/components/chrome/DesktopNav.astro
    See in use
  • Footer

    Site navigation, contact information, and supporting links.

    src/components/chrome/Footer.astro
    See in use
  • Header

    The shared wordmark, primary navigation, and contact link.

    src/components/chrome/Header.astro
    See in use
  • MobileNav

    The mobile navigation modal with outside-click and Escape dismissal, focus containment, and scroll locking.

    src/components/chrome/MobileNav.astro
    See in use
  • ThemeToggle

    Light/dark switch (aria-pressed). Follows the OS until the visitor picks a theme, then remembers it.

    src/components/chrome/ThemeToggle.astro
    See in use
  • SkipLink

    The first keyboard stop, taking readers directly to main content.

    src/components/chrome/SkipLink.astro
    See in use
Layout2
  • Container

    Content widths with a shared 24px horizontal gutter.

    src/components/layout/Container.astro
    See in use
  • Section

    Surface and spacing wrapper used by case studies and supporting pages.

    src/components/layout/Section.astro
    See in use
Type, links & icons5
  • Heading

    Heading semantics and visual size controlled independently.

    src/components/primitives/Heading.astro
    See in use
  • Icon

    Iconify icons with decorative or explicitly labeled semantics.

    src/components/primitives/Icon.astro
    See in use
  • Link

    Navigation, inline, and arrow links used by the site chrome and legal pages.

    src/components/primitives/Link.astro
    See in use
  • Logo

    The Style Script wordmark used in the header and footer.

    src/components/primitives/Logo.astro
    See in use
  • Text

    Body, caption, and supporting text used by case studies and supporting pages.

    src/components/primitives/Text.astro
    See in use
Form controls5
  • Field

    A visible label with optional hint, required marker, and a speech-bubble error.

    src/components/form/Field.astro
    See in use
  • FormAlert

    Polite success status or assertive error feedback.

    src/components/form/FormAlert.astro
    See in use
  • Input

    Text, email, and phone inputs used by the contact form.

    src/components/form/Input.astro
    See in use
  • SubmitButton

    Primary action with ready, busy, and disabled states.

    src/components/form/SubmitButton.astro
    See in use
  • Textarea

    Multiline input with explicit label and description references.

    src/components/form/Textarea.astro
    See in use
Content & media patterns39
  • LiveEmbed

    An optional, explicitly loaded live website preview.

    src/components/patterns/LiveEmbed.astro
    See in use
  • ScrapPiece

    One or more screenshots in a hairline panel on personal project pages.

    src/components/patterns/scrapbook/ScrapPiece.astro
    See in use
  • ScrapMosaic

    A tidy grid of details cut from a personal project's real screens.

    src/components/patterns/scrapbook/ScrapMosaic.astro
    See in use
  • CaseReview

    Case-study shortcuts to the summary, interface, and outcomes.

    src/components/patterns/CaseReview.astro
    See in use
  • CaseSection

    One case-study section: sticky heading, body column, and a media slot for full-width plates.

    src/components/patterns/case/CaseSection.astro
    See in use
  • CaseFindings

    Counted audit findings: a large figure, what it counts, and one line of detail.

    src/components/patterns/case/CaseFindings.astro
    See in use
  • CaseProse

    Case-study body paragraphs, in the body column or continued between plates.

    src/components/patterns/case/CaseProse.astro
    See in use
  • CaseCards

    A grid of titled points with icons, with optional checklists for audience needs.

    src/components/patterns/case/CaseCards.astro
    See in use
  • HeuristicScores

    Nielsen heuristic scores before and after, with the fix and what's still open.

    src/components/patterns/case/HeuristicScores.astro
    See in use
  • CasePersonas

    Personas with needs, frustrations, and a line saying what each one is based on.

    src/components/patterns/case/CasePersonas.astro
    See in use
  • CaseJourney

    A journey map as live text on a route of stage icons that draws in on scroll: stages side by side on large screens, a vertical timeline on small ones, with design responses in one accent-tinted band.

    src/components/patterns/case/CaseJourney.astro
    See in use
  • CaseFor

    A line tying a design decision to its personas and journey stage, with links to both.

    src/components/patterns/case/CaseFor.astro
    See in use
  • CaseResults

    Headline metrics and results grouped by who they changed things for.

    src/components/patterns/case/CaseResults.astro
    See in use
  • CaseQuote

    A client or user testimonial with name, role, and optional photo.

    src/components/patterns/case/CaseQuote.astro
    See in use
  • CaseLimitations

    The closing list of limitations and next steps, with an optional later group.

    src/components/patterns/case/CaseLimitations.astro
    See in use
  • DriftSample

    A component drawn as designed or with drifted properties, for Spot the drift.

    src/components/patterns/DriftSample.astro
    See in use
  • GameStage

    Picks the right game island for a game page or a post embed.

    src/components/patterns/GameStage.astro
    See in use
  • QuizVisual

    The image or interface scene shown above a game question.

    src/components/patterns/QuizVisual.astro
    See in use
  • CodeBlock

    A captioned code artifact with article-matched syntax highlighting, line numbers, and a copy action. Renders fenced code in posts and tool essays.

    src/components/patterns/CodeBlock.astro
  • FidelityBand

    A case-study comparison of design fidelity and implementation.

    src/components/patterns/FidelityBand.astro
    See in use
  • Lightbox

    The shared artifact viewer, with zoom and keyboard dismissal.

    src/components/patterns/Lightbox.astro
    See in use
  • Metric

    A measured result with a label and supporting context.

    src/components/patterns/Metric.astro
    See in use
  • Plate

    A full design sheet with a caption and keyboard-accessible zoom.

    src/components/patterns/Plate.astro
    See in use
  • Portrait

    The responsive photograph used on the home and about pages.

    src/components/patterns/Portrait.astro
    See in use
  • Breadcrumbs

    The trail at the top of every page below a section index.

    src/components/patterns/Breadcrumbs.astro
    See in use
  • ProjectHero

    A project title, ownership details, evidence, and interface preview.

    src/components/patterns/ProjectHero.astro
    See in use
  • GalleryLink

    Points from a case study to its gallery of extra screens and wireframes.

    src/components/patterns/GalleryLink.astro
    See in use
  • ProjectNext

    A large link to the next project, using the shared project data.

    src/components/patterns/ProjectNext.astro
    See in use
  • Recommendation

    A quotation attributed to a named colleague, in regular and featured layouts.

    src/components/patterns/Recommendation.astro
    See in use
  • ScrollShot

    A scrollable long-page screenshot with an inspection control.

    src/components/patterns/ScrollShot.astro
    See in use
  • SiteShot

    A website screenshot with a caption and optional image viewer.

    src/components/patterns/SiteShot.astro
    See in use
  • Tldr

    A project summary with expandable decisions, evidence, and reflection.

    src/components/patterns/Tldr.astro
    See in use
  • ToolIllustration

    An explanatory SVG for each of the four tools.

    src/components/patterns/ToolIllustration.astro
    See in use
  • GameIllustration

    A playful explanatory SVG for each /play/ game.

    src/components/patterns/GameIllustration.astro
    See in use
  • RoleIllustration

    A decorative SVG for each job title in the about page's roles section.

    src/components/patterns/RoleIllustration.astro
    See in use
  • ProjectIllustration

    An explanatory SVG for each case-study hero, drawn in the same style as the tool illustrations.

    src/components/patterns/ProjectIllustration.astro
    See in use
  • ProjectScreenshot

    A cropped app screen for each project in WorkList, in the same mat and frame as the illustrations.

    src/components/patterns/ProjectScreenshot.astro
    See in use
  • ArticleIllustration

    An explanatory SVG for each article, drawn in the same style as the tool illustrations.

    src/components/patterns/ArticleIllustration.astro
    See in use
  • WorkList

    Selected case studies with interface images, roles, and results.

    src/components/patterns/WorkList.astro
    See in use
Interactive features16
  • ContactForm

    Client-side validation, submission, and status handling for contact messages.

    src/components/islands/ContactForm.astro
    See in use
  • ContrastGame

    A ten-round WCAG contrast guessing game built from faded site tokens.

    src/components/islands/ContrastGame.astro
    See in use
  • CopyButton

    A clipboard action with visible and announced feedback.

    src/components/islands/CopyButton.astro
    See in use
  • Diagnostic

    An interactive sample audit with review findings and proposed fixes.

    src/components/islands/Diagnostic.astro
    See in use
  • InspectorMode

    A keyboard-activated layout overlay for inspecting the site.

    src/components/islands/InspectorMode.astro
    See in use
  • DriftGame

    Compare two copies of a component and pick the properties that drifted.

    src/components/islands/DriftGame.astro
    See in use
  • JustEnoughGame

    Slide faded text down to the edge of WCAG AA and score how close you land.

    src/components/islands/JustEnoughGame.astro
    See in use
  • OutlineGame

    Raise and lower heading levels with a live outline check.

    src/components/islands/OutlineGame.astro
    See in use
  • QuizGame

    A multiple-choice game with explanations, used by the /play/ games.

    src/components/islands/QuizGame.astro
    See in use
  • RoiCalculator

    A rework estimate that recalculates from the reader’s inputs.

    src/components/islands/RoiCalculator.astro
    See in use
  • ScorecardEngine

    A design-system self-assessment with local progress and report output.

    src/components/islands/ScorecardEngine.astro
    See in use
  • SnapGridGame

    Nudge pieces onto an 8px grid with buttons, arrow keys, or dragging.

    src/components/islands/SnapGridGame.astro
    See in use
  • TabOrderGame

    Reorder form controls and replay the focus order across the layout.

    src/components/islands/TabOrderGame.astro
    See in use
  • ToolBench

    The tools page's list: a small working piece of each tool on tiles that share radius and spacing values.

    src/components/islands/ToolBench.astro
    See in use
  • TokenPlayground

    Live controls showing how shared tokens change several UI elements.

    src/components/islands/TokenPlayground.astro
    See in use
  • ViewSource

    An optional Alt/Option-hover overlay for elements carrying source metadata.

    src/components/islands/ViewSource.astro
    See in use
Article components1
  • ArticleTable

    A labeled, keyboard-scrollable table region that preserves column headings. Renders any Markdown table in a post. No current post has one.

    src/components/writing/ArticleTable.astro

For coding agents

The same sources build one JSON file with everything on this page. In the repository it lives at design-system/system.json.

Contents of system.json

  • tokens: every color, font, and easing from design-system/tokens.json, with its CSS variable and Tailwind key.
  • rules: the enforced rules, prop-value policy, and the guidelines a script can’t check, from rules.json.
  • components: each component’s path, purpose, an example page, and its props read from the source.
  • audits: the commands to run before calling UI work done.

Rules for changes

  • Build from existing components and token utilities. A new pattern isn’t part of the system until it appears here and in the component catalog.
  • When audit:design fails, fix the code. Adding tokens, exceptions, or baseline entries is a design-system decision that needs approval.
  • Use accent, never a hard-coded accent hex, so it follows the surface.
Open system.json
Terminal bash
# In the repo (regenerated on commit)
cat design-system/system.json
npm run design:context

# From anywhere
curl https://joshuabriley.com/style-guide/system.json

# Before calling UI work done
npm run audit:design
npm run audit:components
npm run audit:contrast