Guidelines

Foundations

Guidelines v2.0.0

Shellui design tokens for color, type, spacing, and radius on web and in print. Generated tables stay in sync with tokens/tokens.json.

Download markdown tokens.json

For agents

Fetch markdown, not this HTML. Token tables are generated from tokens/tokens.json. 

https://shellui.com/guidelines/foundations.md
https://shellui.com/guidelines/generated/tokens.json

Foundations are the shared numbers: color, type, spacing, and radius. Values on this page are generated from tokens/tokens.json at build time. If a hex here disagrees with prose elsewhere, trust this page.

  • Web: Inter on screen (self-hosted on shellui.com). Token utilities in Tailwind (bg-primary, text-primary-ink, and the rest).
  • Print: IBM Plex Sans and Plex Mono. See Print for grid, folios, and Pantone.
  • Interface: how to compose pages with these tokens. See Interface.

Downloads

Color tokens (web)

Brand gold #E3A512 is for fills, rules, and the logo, not body text. Text gold is #8A6300 on light backgrounds and #E8B84A in dark mode (primary-ink remaps automatically).

<!-- tokens:begin -->

Token Light Dark Role
primary #e3a512 #e8b84a Accent / buttons
primary-foreground #1a1408 #1a1408 Text on gold
primary-ink #8a6300 #e8b84a Gold text on light; remaps on dark
ring #e3a512 #e8b84a Focus
background #ffffff #030712 Page canvas
foreground #111827 #f9fafb Primary text
muted #f9fafb rgb(255 255 255 / 0.05) Quiet wells
muted-foreground #4b5563 #9ca3af Secondary text
border #e5e7eb #1f2937 Rules, cards
card #ffffff #111827 Raised surface
card-foreground #111827 #f9fafb Text on card
radius rounded-xl cards (0.75rem); rounded-md controls (0.375rem) same Shape
<!-- tokens:end -->

Gold (brand and print)

Name Hex Pantone (coated) Use
Brand gold #E3A512 124 C (7405 U uncoated) Fills, rules, logo
Text gold #8A6300 4027 C Links and gold text on light
Text gold (dark) #E8B84A None Links and gold text on dark
On gold #1A1408 None Text on gold buttons

Verify coated and uncoated Pantone against a physical swatch before the first print run.

Typography

Surface Family Notes
Website and in-shell apps Inter Self-hosted, font-display: swap, Latin subset
Print and PDF kit IBM Plex Sans One family for all print words; Plex Mono for code
Generated images Inter og:image, social banners, icons (not print)

Type scale on the web follows Tailwind defaults already used on shellui.com: page title text-4xl font-bold md:text-5xl, section text-2xl / text-3xl font-semibold, body text-base/7, labels text-sm font-medium. Print sizes live on Print.

Spacing and radius

Token Web Print
Outer gutters .page-x (px-4 sm:px-6 lg:px-8) 20 mm page margin
Below header .page-top Running head only on body pages
Section step mt-10, mt-16 6 mm stacked cards, 8 mm feature gaps
Controls rounded-md (0.375rem) 2 mm radius on frames
Cards rounded-xl (0.75rem) 2 mm on screenshot frames

Motion

Honor prefers-reduced-motion. Animate transform and opacity only, never transition: all. Marketing theme reveal already disables under reduced motion; match that in product UI.

Color

Each swatch shows light on the left and dark on the right. Values come from src/_data/designTokens.js and must match input.css.

Accent

Honey gold is the action color, not a wash. Use it on the primary button, the product eyebrow, and key links.

  • Light #e3a512
    Dark #e8b84a

    primary

    Accent / buttons

    #e3a512 #e8b84a

  • Light #1a1408
    Dark #1a1408

    primary-foreground

    Text on gold

    #1a1408 #1a1408

  • Light #8a6300
    Dark #e8b84a

    primary-ink

    Gold text on light; remaps on dark

    #8a6300 #e8b84a

  • Light #e3a512
    Dark #e8b84a

    ring

    Focus

    #e3a512 #e8b84a

Canvas

Pages sit on a gray field. Light and dark are both first-class.

  • Light #ffffff
    Dark #030712

    background

    Page canvas

    #ffffff #030712

  • Light #111827
    Dark #f9fafb

    foreground

    Primary text

    #111827 #f9fafb

  • Light #f9fafb
    Dark rgb(255 255 255 / 0.05)

    muted

    Quiet wells

    #f9fafb white/5

  • Light #4b5563
    Dark #9ca3af

    muted-foreground

    Secondary text

    #4b5563 #9ca3af

Structure

Earn a border or raised surface when spacing cannot express the grouping.

  • Light #e5e7eb
    Dark #1f2937

    border

    Rules, cards

    #e5e7eb #1f2937

  • Light #ffffff
    Dark #111827

    card

    Raised surface

    #ffffff #111827

  • Light #111827
    Dark #f9fafb

    card-foreground

    Text on card

    #111827 #f9fafb

Type

System font stack. Sentence-case headings. One h1. Rewrite before shrinking the measure.

Page title

Build the app

text-4xl font-bold md:text-5xl

Section

Shared authentication

text-2xl / text-3xl font-semibold tracking-tight

Lede

The shell wraps your app with navigation, auth, admin, and storage.

text-lg text-muted-foreground

Body

Lead with what ships today. Keep AI, MCP, and marketplace chrome quiet unless the page is about that surface.

text-base/7

Label

Developers

text-sm font-medium

Mono

bg-primary text-primary-ink

font-mono text-xs

Shape and space

Controls are tighter than cards. Vertical rhythm comes from heading-to-body proximity and larger gaps at section turns.

Radius

  • rounded-sm

    0.25rem · Tight chips

  • rounded-md

    0.375rem · Buttons and controls

  • rounded-lg

    0.75rem · @theme radius-lg

  • rounded-xl

    0.75rem · Cards and wells

Spacing

  • page-x

    Outer horizontal gutters

  • page-top

    Clear fixed header

  • mt-10

    Section step

  • mt-16

    Larger section turn

Actions

One primary button. The secondary is a text link. Gold stays scarce.

Get started View on GitHub Guidelines Hover Focus

Surfaces

The page is one continuous canvas. These islands lock light and dark tokens so you can compare them without toggling the site theme.

light

Shellui

Shared authentication

The shell wraps the app with sign-in, admin, and storage so you can ship the product.

Get started View on GitHub →

Config

shellui.config.ts

Quiet well · muted

dark

Shellui

Shared authentication

The shell wraps the app with sign-in, admin, and storage so you can ship the product.

Get started View on GitHub →

Config

shellui.config.ts

Quiet well · muted

Composition

Start with the reader's job. The first viewport is the argument. Reuse layouts already in this repo before inventing a kit.

  • Reader first

    Identify what they need to understand or decide, the strongest supported answer, and the evidence that earns it.

  • One focal relationship

    Surround it with a few supporting objects and enough open space. Equal-weight blocks mean redesign.

  • Reuse Plus patterns

    Centered hero, feature split, two-tier pricing, FAQ list, quiet CTA band. Restyle with these tokens. Soft primary/amber ambient on the homepage hero is allowed.

  • What ships today

    Iframe host, SDK, auth, admin, storage, Files. Keep AI and marketplace chrome quiet unless the page is about that surface.

Do and don't

Same material, two compositions. The left reuses the shipped dual-CTA opening. The right is the generic grid this system rejects.

Do

One claim, one primary action, gray canvas, scarce gold. Soft primary ambient behind the hero is brand warmth.

Shellui

Build the app, not the infrastructure

Shared auth, admin, and storage around your iframe app.

Get started GitHub →
Don't

Equal-weight cards, gold headings, and banned marketing words.

Unlock the platform

Auth

Seamless. Easy.

Admin

Seamless. Easy.

Storage

Seamless. Easy.

AI

Seamless. Easy.