Skip to content
Menu
Close
Guide
Reference
Blog
Jig
v0.25
(all versions)
Guide
Reference
Blog
Switch to dark theme
Switch to light theme
GitHub
Sections
Overview
Things to avoid
129
129 rules
Generic-AI aesthetic
25
25 rules
Purple and violet as the unspecified default
Gradient text on headings
Decorative gradient blobs and orbs
Trend styles that fight legibility
Decorative styling that implies meaning
Repeated information
Icons all competing at equal weight
A container around every group
Emoji as interface iconography
The three-column feature grid reflex
Oversized radius everywhere
Shadow as the only depth cue
Marketing voice in an application
Placeholder content shipped
A kicker above every heading
An eyebrow chip over the headline
Cream and beige by reflex
An italic serif display headline
A side-tab accent border
A thick coloured border on a rounded element
Cards inside cards
The soft rounded card
A decorative grid or stripe background
Dark mode with glowing accents
Numbered section labels
Typography
13
13 rules
Unbounded line length
Centred or justified body text
One line-height for everything
Thin weights for body text
Ad-hoc type sizes
All-caps for anything long
Skipping heading levels for visual reasons
Long-form text below 18px
More than two typefaces
More than two font weights
Text placed directly on a photo
Monospace sized by a guessed ratio
A word stranded on its own line
Colour and contrast
9
9 rules
Depth built from shadow in dark mode
Pure black on pure white
Grey text below contrast floor
Colour as the sole signal
Dark mode by inversion
Semantic colours invented inline
Link treatment
Coloured heading text
Non-interactive elements styled like interactive ones
Spacing and layout
14
14 rules
Spacing off the scale
Symmetric spacing around headings
Spacing that does not grow outward
Icon and text out of balance
Broken left edge
Multiple alignments in one component
Mixed-size text centred vertically
No proximity hierarchy
One padding value for all containers
Optical alignment ignored
A page that never adapts to the viewport
A full-height section sized with
100vh
A pinned bar under the notch or the home indicator
The page scrolls sideways on a phone
States and interaction
23
23 rules
Missing states
Focus removed without replacement
Empty states omitted
Hover-only affordances
Disabled buttons
div
with a click handler
Icon-only controls without names
Dynamic results with no announcement
Icon without a visible label
Unconventional controls
Important navigation hidden when it fits
Off-screen content with no affordance
Minimal but unreadable
Brand colour colliding with a system meaning
More than one interactive colour
Interface built only for short content
Truncating where items share a prefix
Button hierarchy carried by colour alone
Light grey secondary button
Inconsistent button shapes
Destructive actions coloured red at rest
Primary action parked at the right
A menu that cannot be opened, or does not say it is open
Forms
16
16 rules
Placeholder as label
Unhelpful error text
Validation timing wrong at both ends
Input cleared on error
Missing input affordances
Critical function dependent on JavaScript
Required fields left unmarked
Labels beside inputs
Uniform field widths
A dropdown for a small set of options
A long dropdown where autocomplete belongs
Toggle and checkbox used interchangeably
Negatively phrased checkbox labels
Instructional verbs in labels
Form text small enough to make the phone zoom
Asking for more than the task needs
Motion
7
7 rules
Entrance animation on everything
prefers-reduced-motion
ignored
A pulsing status dot
Durations too long
A layout change that jumps
Animating layout, or everything
Several things moving at once
Code-level
6
6 rules
New component instead of the existing one
Local convention overridden
Values hard-coded past the token layer
JavaScript for something CSS does
A generic element where a native one says what the content is
A token name nothing declares
Search and sharing
9
9 rules
Metadata that no longer matches the page
An indexable page with no title or description of its own
Metadata past its budget
A page that must not be indexed and does not say so
A sitemap that contradicts the page
Invented facts in metadata
Structured data retyped instead of read
A list served as a fact when it is empty
An indexable page a link preview cannot read
Safety at the interface
7
7 rules
A new-tab link that hands over the page it left
User content written as markup
Credential fields that fight the password manager
A frame with no sandbox, a script from anywhere
A secret rendered as plain text
An error that describes the system
Inline handlers on a page with a content policy
Self-check before finishing
Interface modes
4
4 specs
Choosing a mode
editorial
product
operator
Design Tokens
10
10 specs
Architecture
Why CSS custom properties
Predefined option sets
Sizes and motion, by mode
Colour naming
Naming contract
Colour architecture
Contrast contract
Dark mode
Consuming
Components and layout
16
16 specs
Feedback placement
Button
Form field
Choosing an input control
Form
Empty state
Data table
Dialog
Loading
Interaction cost
Progressive disclosure
Ambient motion
Site navigation
Layout method
Building modularly
Adding a pattern
Principles
12
12 specs
Frames
5
5 specs
Frame 1: Minimise usability risk
Frame 2: Every detail has a reason you can state
Frame 3: Minimise interaction cost
Frame 4: Minimise cognitive load
Frame 5: Optimise for the common path
Tiebreakers
7
7 specs
Tiebreaker 1: Prefer the loud failure
Tiebreaker 2: Never destroy on suspicion
Tiebreaker 3: Recoverable beats correct
Tiebreaker 4: Optimise for who is actually there
Tiebreaker 5: Restraint is the default
Tiebreaker 6: The platform before the framework
Tiebreaker 7: Match the codebase before matching this document
UI writing
31
31 rules
Voice
3
3 rules
Title Case Used For Interface Text
Vague or inflated language
Padding words and introductory phrases
Structure
4
4 rules
Text that buries the point
Long text without a structure
Vague headings
Uneven text length across parallel elements
Words
6
6 rules
Numbers spelled out
Abbreviations and acronyms
UPPERCASE
Full stops on fragments
Em dashes in interface text
Inconsistent vocabulary
Labels and links
4
4 rules
"My" or "your" on form labels
Generic link text
Actions and text centred by default
Brand colour spent on decoration
Errors
1
1 rule
Error messages that report without helping
Prose
9
9 rules
A claim with no source
Specific in sound, empty in fact
Formula openers, closers and signposts
Saying it twice
A rhetorical shape on repeat
Enthusiasm the content has not earned
Stacked hedges
Emoji in headings
Structure imposed rather than earned
Long-form
4
4 rules
Nothing only the author could say
No point of view
An even rhythm
Feeling named, not shown
Copy checklist
Overview
Things to avoid
129
129 rules
Generic-AI aesthetic
25
25 rules
Purple and violet as the unspecified default
Gradient text on headings
Decorative gradient blobs and orbs
Trend styles that fight legibility
Decorative styling that implies meaning
Repeated information
Icons all competing at equal weight
A container around every group
Emoji as interface iconography
The three-column feature grid reflex
Oversized radius everywhere
Shadow as the only depth cue
Marketing voice in an application
Placeholder content shipped
A kicker above every heading
An eyebrow chip over the headline
Cream and beige by reflex
An italic serif display headline
A side-tab accent border
A thick coloured border on a rounded element
Cards inside cards
The soft rounded card
A decorative grid or stripe background
Dark mode with glowing accents
Numbered section labels
Typography
13
13 rules
Unbounded line length
Centred or justified body text
One line-height for everything
Thin weights for body text
Ad-hoc type sizes
All-caps for anything long
Skipping heading levels for visual reasons
Long-form text below 18px
More than two typefaces
More than two font weights
Text placed directly on a photo
Monospace sized by a guessed ratio
A word stranded on its own line
Colour and contrast
9
9 rules
Depth built from shadow in dark mode
Pure black on pure white
Grey text below contrast floor
Colour as the sole signal
Dark mode by inversion
Semantic colours invented inline
Link treatment
Coloured heading text
Non-interactive elements styled like interactive ones
Spacing and layout
14
14 rules
Spacing off the scale
Symmetric spacing around headings
Spacing that does not grow outward
Icon and text out of balance
Broken left edge
Multiple alignments in one component
Mixed-size text centred vertically
No proximity hierarchy
One padding value for all containers
Optical alignment ignored
A page that never adapts to the viewport
A full-height section sized with
100vh
A pinned bar under the notch or the home indicator
The page scrolls sideways on a phone
States and interaction
23
23 rules
Missing states
Focus removed without replacement
Empty states omitted
Hover-only affordances
Disabled buttons
div
with a click handler
Icon-only controls without names
Dynamic results with no announcement
Icon without a visible label
Unconventional controls
Important navigation hidden when it fits
Off-screen content with no affordance
Minimal but unreadable
Brand colour colliding with a system meaning
More than one interactive colour
Interface built only for short content
Truncating where items share a prefix
Button hierarchy carried by colour alone
Light grey secondary button
Inconsistent button shapes
Destructive actions coloured red at rest
Primary action parked at the right
A menu that cannot be opened, or does not say it is open
Forms
16
16 rules
Placeholder as label
Unhelpful error text
Validation timing wrong at both ends
Input cleared on error
Missing input affordances
Critical function dependent on JavaScript
Required fields left unmarked
Labels beside inputs
Uniform field widths
A dropdown for a small set of options
A long dropdown where autocomplete belongs
Toggle and checkbox used interchangeably
Negatively phrased checkbox labels
Instructional verbs in labels
Form text small enough to make the phone zoom
Asking for more than the task needs
Motion
7
7 rules
Entrance animation on everything
prefers-reduced-motion
ignored
A pulsing status dot
Durations too long
A layout change that jumps
Animating layout, or everything
Several things moving at once
Code-level
6
6 rules
New component instead of the existing one
Local convention overridden
Values hard-coded past the token layer
JavaScript for something CSS does
A generic element where a native one says what the content is
A token name nothing declares
Search and sharing
9
9 rules
Metadata that no longer matches the page
An indexable page with no title or description of its own
Metadata past its budget
A page that must not be indexed and does not say so
A sitemap that contradicts the page
Invented facts in metadata
Structured data retyped instead of read
A list served as a fact when it is empty
An indexable page a link preview cannot read
Safety at the interface
7
7 rules
A new-tab link that hands over the page it left
User content written as markup
Credential fields that fight the password manager
A frame with no sandbox, a script from anywhere
A secret rendered as plain text
An error that describes the system
Inline handlers on a page with a content policy
Self-check before finishing
Interface modes
4
4 specs
Choosing a mode
editorial
product
operator
Design Tokens
10
10 specs
Architecture
Why CSS custom properties
Predefined option sets
Sizes and motion, by mode
Colour naming
Naming contract
Colour architecture
Contrast contract
Dark mode
Consuming
Components and layout
16
16 specs
Feedback placement
Button
Form field
Choosing an input control
Form
Empty state
Data table
Dialog
Loading
Interaction cost
Progressive disclosure
Ambient motion
Site navigation
Layout method
Building modularly
Adding a pattern
Principles
12
12 specs
Frames
5
5 specs
Frame 1: Minimise usability risk
Frame 2: Every detail has a reason you can state
Frame 3: Minimise interaction cost
Frame 4: Minimise cognitive load
Frame 5: Optimise for the common path
Tiebreakers
7
7 specs
Tiebreaker 1: Prefer the loud failure
Tiebreaker 2: Never destroy on suspicion
Tiebreaker 3: Recoverable beats correct
Tiebreaker 4: Optimise for who is actually there
Tiebreaker 5: Restraint is the default
Tiebreaker 6: The platform before the framework
Tiebreaker 7: Match the codebase before matching this document
UI writing
31
31 rules
Voice
3
3 rules
Title Case Used For Interface Text
Vague or inflated language
Padding words and introductory phrases
Structure
4
4 rules
Text that buries the point
Long text without a structure
Vague headings
Uneven text length across parallel elements
Words
6
6 rules
Numbers spelled out
Abbreviations and acronyms
UPPERCASE
Full stops on fragments
Em dashes in interface text
Inconsistent vocabulary
Labels and links
4
4 rules
"My" or "your" on form labels
Generic link text
Actions and text centred by default
Brand colour spent on decoration
Errors
1
1 rule
Error messages that report without helping
Prose
9
9 rules
A claim with no source
Specific in sound, empty in fact
Formula openers, closers and signposts
Saying it twice
A rhetorical shape on repeat
Enthusiasm the content has not earned
Stacked hedges
Emoji in headings
Structure imposed rather than earned
Long-form
4
4 rules
Nothing only the author could say
No point of view
An even rhythm
Feeling named, not shown
Copy checklist
More below
Reference
Design Tokens
10 specs
Architecture
Why CSS custom properties
Predefined option sets
Sizes and motion, by mode
Colour naming
Naming contract
Colour architecture
Contrast contract
Dark mode
Consuming