GFS Design System — Design Specification

02 Typography System Type scale, weights, pairing, number formats

Complete Type Scale

Every text element must use one of these tokens. No arbitrary font sizes. No exceptions.

--text-xs · 11px IBM Plex Mono · Uppercase · letter-spacing .06em+

Labels, badges, system meta, timestamps, table headers, button text, tab labels

font-family: 'IBM Plex Mono', monospace; font-size: var(--text-xs); letter-spacing: .06em; text-transform: uppercase;

--text-sm · 13px Inter 400 · Normal case

Secondary body text, table cell content, descriptions, form hints, card descriptions. This is the workhorse size for dense UI.

font-size: var(--text-sm); color: var(--graphite);

--text-base · 15px Inter 400 · Primary body text

Primary body text. This is the default reading size for paragraphs, modal content, and page descriptions. Line height is 1.6 for comfortable reading.

font-size: var(--text-base); line-height: 1.6; color: var(--black);

--text-lg · 17px Inter 600 · Card titles, sub-headings

Card titles and sub-headings within sections

font-size: var(--text-lg); font-weight: 600;

--text-xl · 20px Inter 700 · Section sub-titles

Section sub-titles and secondary headings

font-size: var(--text-xl); font-weight: 700; color: var(--cobalt);

--text-2xl · 24px Inter 800 · Page section titles

Page Section Titles

font-size: var(--text-2xl); font-weight: 800; color: var(--cobalt);

--text-3xl · 32px Inter 800 · KPI values, hero stats

$29.4M

font-size: var(--text-3xl); font-weight: 800; line-height: 1.1;

--text-4xl · 40px Inter 900 · Page hero titles

Page Hero Title

font-size: var(--text-4xl); font-weight: 900; line-height: 1.1; letter-spacing: -.02em;

Font Weight Rules

Weight	Token	Usage	Specimen
400	Regular	Body text, descriptions, table cells	Global Food Solutions
500	Medium	Emphasized body, active nav items	Global Food Solutions
600	Semibold	Card titles, labels, form labels, active tabs	Global Food Solutions
700	Bold	Section headings, sub-titles	Global Food Solutions
800	Extrabold	Page titles, KPI values, hero elements	Global Food Solutions
900	Black	Hero title only (text-4xl and above)	Global Food Solutions

Line Height Rules

1.1 — Headings

Tight line height for large display text and KPI values.

1.4 — UI Text

Used for table cells, labels, badges, navigation items, and any compact interface text where space is at a premium.

1.6 — Body Paragraphs

Used for readable body text, descriptions, modal content, and any paragraph-length content where readability matters most.

Paragraph & Heading Spacing

Spacing Between Paragraphs

16px (--sp-4) between consecutive paragraphs. 24px (--sp-6) after headings before the first paragraph.

Spacing Specimen

Section Heading

24px (--sp-6)

First paragraph after a heading. This paragraph describes the section content.

16px (--sp-4)

Second paragraph. Standard spacing between body paragraphs.

Truncation Rules

Single-Line Ellipsis

This is a very long customer name that should be truncated with an ellipsis when it reaches the container width

white-space: nowrap; overflow: hidden; text-overflow: ellipsis;

Multi-Line Clamp (3 lines)

This is a longer piece of card description text that should be clamped to exactly three lines using the -webkit-line-clamp property. After three lines, the text will be truncated with an ellipsis. If the user needs to see more content, provide a "Show more" link below the clamped text.

display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden;

Number Formatting Specification

Currency (standard)

$1,234.56

Always 2 decimals, comma separator. Example: $48.30, $1,200.00

Currency (abbreviated)

$1.2M

Abbreviate above $9,999. Use K for thousands, M for millions. Example: $48.3K, $1.2M

Percentages

96.2%

1 decimal place. No decimal when whole number: 100%, 50%. Example: 96.2%, 100%

Dates (tables)

05/20/2026

MM/DD/YYYY in tables and data. "May 20, 2026" in prose and narrative text.

Phone

(877) 728-5550

Parentheses around area code, dash between groups. Never dots or spaces.

Weight

18,420 lbs

Comma separator, lowercase "lbs". Example: 42 lbs, 18,420 lbs

Temperature

35°F

Degree symbol, uppercase F. No space. Example: 35°F, -10°F

Document IDs

SO-24871

Prefix + dash + 5 digits. SO-24871, PO-10447, INV-08841

Heading Hierarchy

H1 is Reserved

H1 is NEVER used in page content. It is reserved for the page title in the hero section. All visible content starts at H2.

Element	Usage	Specimen
h2	Major page sections	Section Title
h3	Sub-sections within a section	Sub-Section
h4	Component labels, card headers	Component Label

Font Pairing Rules

Inter — All Readable Text

Headings, body paragraphs, card content, modal text, descriptions, page titles, KPI values.

$1.2M Revenue

Global Food Solutions processes over 42,000 orders per year across all facility locations.

IBM Plex Mono — All System Text

Labels, badges, table headers, button text, tab labels, form labels, timestamps, metadata, codes.

TOTAL REVENUE · SO-24871 · SHIPPED · 05/20/2026

Customer name · Ship date · Est. delivery

Never: Mix the two fonts within the same text element. Inter for readable content, Plex Mono for system/data content. No exceptions.

Font Rendering

Anti-Aliasing

All pages must include -webkit-font-smoothing: antialiased and -moz-osx-font-smoothing: grayscale on the html element. This is already set in shared.css. Never override it.

Font Loading Strategy

Google Fonts must be loaded with rel="preconnect" for both fonts.googleapis.com and fonts.gstatic.com. Use display=swap to prevent FOIT (Flash of Invisible Text).

Tabular Numbers for Data

Always Use font-variant-numeric: tabular-nums for Columns

When numbers appear in table columns or KPI grids, they must use tabular (monospaced) figures so decimal points and digits align vertically.

Without tabular-nums (Wrong)

$1,234.56

$48,320.00

$111.11

$6,150.00

With tabular-nums (Correct)

$1,234.56

$48,320.00

$111.11

$6,150.00

Letter Spacing Reference

Value	Usage	Specimen
-.035em	Hero titles (text-7xl only)	DESIGN
-.02em	Page titles (text-4xl, text-5xl)	Page Title
0	Body text, descriptions (default)	Standard body text uses default spacing.
.04em	Badge text, toast text	Badge Text
.06em	Table headers, button text, labels	Table Header
.08em	Topbar text, sidebar group headers	Topbar Label
.1em	Section header titles	Section Head
.12em	Hero taglines, eyebrow text	Hero Tagline
.15em	Hero eyebrow labels	Eyebrow Label
.2em	Vertical text, monogram subtitles	Vert Text

■ Typography system defines the entire text hierarchy. Every text element maps to exactly one token.

03 Spacing & Layout Rules Page widths, spacing tokens, density, 4px grid

Page Width Maximums

Full-Width Reference Pages

1200px max-width with 24px side padding. Used for design system reference pages, specification documents.

max-width: 1200px; padding: 0 24px;

Portal / Dashboard Pages

100% width with 200px sidebar + fluid content area. Content fills remaining space.

200px

fluid content

Print Templates

8.5" x 11" (816px content width). Standard US letter size.

Email Templates

600px max-width. Ensures compatibility with all major email clients.

Spacing Token Reference

--sp-1
4px

--sp-2
8px

--sp-3
12px

--sp-4
16px

--sp-5
20px

--sp-6
24px

--sp-8
32px

--sp-10
40px

--sp-12
48px

Spacing Application Rules

Context	Token	Value	Rule
Between major sections	--sp-8	32px	Space between top-level page sections
Between sub-sections	--sp-6	24px	Space between sub-sections within a section
Card padding (standard)	--sp-5	20px	Default padding inside cards
Card padding (compact)	--sp-4	16px	Compact cards, KPI cards, dense layouts
Card padding (featured)	--sp-6	24px	Featured/hero cards, spotlight content
Card gap in grids	--sp-4	16px	Gap between cards in grid layouts
Form field spacing	--sp-5	20px	Space between form groups
Table cell vertical	--sp-3	12px	Top/bottom padding in table cells
Table cell horizontal	--sp-4	16px	Left/right padding in table cells

Density Modes

Order	Customer	Amount	Status
SO-24871	Driscoll Foods	$48,320.00	Shipped
SO-24872	Key Food Stores	$12,480.00	Pending
SO-24873	C-Town Supermarkets	$6,150.00	Processing

Comfortable: default spacing, 44px row height, 15px font

The 4px Grid

Mandatory: All Spacing Divisible by 4

Every spacing value in the system is divisible by 4px. The --sp-* tokens enforce this. Never use arbitrary pixel values like 5px, 7px, 9px, 11px, 13px, 15px, or any value not on the 4px grid. This includes margins, paddings, gaps, and component dimensions.

Container Nesting

Maximum 3 Levels of Nested Borders

Never nest more than 3 levels of bordered containers. Beyond that, visual noise increases and the hierarchy becomes unclear.

Nesting Example — Maximum Depth

Level 1: Page Section

Level 2: Card

Level 3: Inner Component (Maximum)

Content goes here. No further nested borders allowed.

Margin vs Gap vs Padding

Method	When to Use	Example
gap	Between sibling elements in flex/grid containers	Card grids, button groups, form rows
padding	Space inside a container, between border and content	Card content, section bodies, cells
margin	Space between unrelated elements outside a flex/grid	Between sections, after headings

Prefer gap over margin

Whenever elements are in a flex or grid container, use gap instead of margin. Gap prevents margin collapse issues and is more predictable.

Responsive Behavior Summary

Breakpoint	Layout Change
1280px+	Full layout: sidebar + content + secondary panel
1024px	Sidebar collapses to icons only, secondary panel hidden
768px	Sidebar becomes top nav or hamburger, 2-col grids become 1-col
550px	Single column everything, 48px min touch targets

■ All spacing is on the 4px grid. Use --sp-* tokens exclusively. Never hardcode pixel values.

04 Color Decision Tree Blues, neutrals, status colors, data viz sequence

Which Blue? Decision Tree

When you need a blue, this tree tells you exactly which one.

Cobalt #092F64

Primary brand color. Use for: headings, primary buttons, button text on light backgrounds, key borders, section number text, card accent borders (3px top), primary text emphasis.

Navy #1A5799

Secondary actions and emphasis. Use for: hover states on cobalt buttons, active sidebar items, secondary action buttons, info-level badge text.

Tufts #468BE6

Interactive elements. Use for: text links, focus rings, chart primary color, active sort indicators, progress bars, spinners, token values in code.

Jordy #93BFEF

Soft accents. Use for: disabled interactive states, chart secondary color, light decorative accents, globe rings, clearspace markers.

Alice #E9F5FF

Highlighted backgrounds. Use for: selected row backgrounds, focus ring glow, info alert backgrounds, accent backgrounds, selection highlight.

Ice #F4F9FF

Subtle backgrounds. Use for: page background tint, card hover states, section note backgrounds, sidebar active background, hero right panel.

Neutral Usage Rules

Black #1F1F1F

Primary text ONLY. Body text, table cell values, card titles. Never for backgrounds or borders.

Graphite #4B5F7A

Secondary text. Descriptions, secondary body text, section header text, form labels.

Slate #6B7280

Tertiary text. Hints, timestamps, KPI labels, metadata, muted navigation items.

Steel #9CA3AF

Disabled text, placeholder text. NEVER for readable content that users need to act on.

Silver #D9E1EA

Borders and dividers. Card borders, table cell dividers, input borders, section separators.

Fog #F0F2F5

Backgrounds. Table header backgrounds, card backgrounds, muted areas, zebra striping rows.

White #FFFFFF

Page background and card surfaces. The default canvas color.

Status Color Rules

Never: Use status colors for non-status purposes. Green means success/positive. Yellow means warning/pending. Red means error/critical. Blue means informational/processing. These are locked meanings.

Success #0F766E

Confirmed, shipped, approved, paid, healthy, passing, delivered, complete.

Shipped

Warning #B45309

Pending, on hold, expiring, attention needed, low stock, watch.

Pending

Error #DC2626

Failed, rejected, overdue, critical, declining, out of stock.

Failed

Info #1A5799

Informational, processing, in progress, in transit, scheduled.

Processing

Data Visualization Color Sequence

Chart Colors: Always in This Order

When charting multiple data series, always assign colors in this exact sequence. Never skip or reorder.

1. COBALT

2. TUFTS

3. SUCCESS

4. WARNING

5. NAVY

6. JORDY

Status Badge Mapping — Every Business Status

Domain	Status	Color	Badge
Sales	Pending Approval	warning	Pending Approval
	Pending Fulfillment	info	Pending Fulfillment
	Partially Fulfilled	info	Partially Fulfilled
	Fulfilled	success	Fulfilled
	Billed	success	Billed
	Closed	gray	Closed
Purchase	Pending Approval	warning	Pending Approval
	Pending Receipt	info	Pending Receipt
	Received	success	Received
	Billed	success	Billed
Invoice	Open	info	Open
	Paid	success	Paid
	Past Due	error	Past Due
	Void	gray	Void
Inventory	In Stock	success	In Stock
	Low Stock	warning	Low Stock
	Out of Stock	error	Out of Stock
	On Order	info	On Order
Quality	Pass	success	Pass
	Fail	error	Fail
	Hold	warning	Hold
	Pending Review	info	Pending Review
Delivery	Scheduled	info	Scheduled
	In Transit	info	In Transit
	Delivered	success	Delivered
	Delayed	warning	Delayed
	Failed	error	Failed
Temperature	Normal	success	Normal
	Warning	warning	Warning
	Critical	error	Critical
Credit	Good Standing	success	Good Standing
	Watch	warning	Watch
	Hold	error	Hold

Background Color Decision Tree

What Kind of Background?

--> Page background: var(--white) — always #FFFFFF in light, #111111 in dark

--> Card surface: var(--white) — cards sit on the page background

--> Table header / muted area: var(--fog) — #F0F2F5 in light

--> Hover / active state: var(--ice) — #F4F9FF in light

--> Selected / highlight: var(--alice) — #E9F5FF in light

--> Success context: var(--success-bg) — #F0FDF4 in light

--> Warning context: var(--warning-bg) — #FFFBEB in light

--> Error context: var(--error-bg) — #FEF2F2 in light

--> Info context: var(--info-bg) — #E9F5FF in light

--> Primary branded: var(--cobalt) — topbar, dark hero panels

Accessible Color Pairs

These are the approved text-on-background combinations. All meet WCAG AA (4.5:1) minimum contrast ratio.

Black on White

Ratio: 15.4:1 — AAA PASS — Primary body text

Cobalt on White

Ratio: 11.3:1 — AAA PASS — Headings, primary emphasis

Graphite on White

Ratio: 6.7:1 — AA PASS — Secondary text, descriptions

Slate on White

Ratio: 4.9:1 — AA PASS — Tertiary text, hints

White on Cobalt

Ratio: 11.3:1 — AAA PASS — Topbar, buttons, dark panels

Steel on White

Ratio: 3.0:1 — AA FAIL for text — Placeholders only, NEVER for readable content

Live Color Context Examples

Total Revenue

$29.4M

+12.3% vs prior year

Fill Rate

96.2%

Target: 95.0% — On Track

Past Due AR

$786K

14 accounts — Needs Attention

Alert Color Application

ⓘ

Processing: Order SO-24871 is being prepared for shipment. Estimated ship date: 05/22/2026.

✓

Shipped: Order SO-24870 has shipped via carrier. Tracking number: 1Z999AA10123456784.

⚠

Low Stock: Barrel Cheddar (SKU BC-40LB) has dropped below reorder point. Current stock: 12 units.

✕

Temperature Alert: Dock 3 has exceeded safe temperature range. Current reading: 48°F. Immediate action required.

■ Never assign a color outside this mapping. When adding new statuses, classify into success/warning/error/info/gray first.

05 Component State Specifications Every interactive state for every component

Button States

Primary Button

Default

bg: cobalt, color: white

Hover

bg: navy, border: navy

Active / Pressed

scale(0.98), bg: navy

Focus

3px alice + 5px tufts ring

Disabled

opacity: 0.4, no-pointer

Loading

spinner replaces text, fixed width

Secondary Button

Default

Hover

Focus

Disabled

Ghost Button

Default

Hover

Focus

Disabled

Danger Button

Default

Hover

Focus

Disabled

Input Field States

Empty

Standard empty state with placeholder

Focused

2px tufts border + 3px alice shadow

Filled

Standard border, black text

Error

Enter a valid customer name

Success

Customer verified

Disabled

fog bg, steel text, no border change

Table Row States

State	Order	Customer	Amount
Default	SO-24871	Driscoll Foods	$48,320.00
Hover	SO-24872	Key Food Stores	$12,480.00
Selected	SO-24873	C-Town Supermarkets	$6,150.00
Loading

Card States

Default

Standard card with silver border.

border: 1px silver

Hover

Lifts 2px with shadow-md.

translateY(-2px) + shadow-md

Selected

Cobalt top border + alice bg.

3px cobalt top + alice bg

Loading

skeleton pulse overlay

Sidebar Navigation States

Navigation
Default Item
Hover State
Active Item
With Badge 3

Toggle, Checkbox & Tab States

Toggles

Off

On

Disabled

Checkboxes

Unchecked

Checked

−

Indeterminate

Disabled

Tabs

Active

Hover

Inactive

Disabled

Complete Form Pattern

A complete form demonstrating all form element states and spacing rules in context.

Create Sales Order

Customer name *

Customer verified

Purchase order #

Optional. Will appear on invoice.

Ship date *

Enter a valid date (MM/DD/YYYY)

Delivery method

Notes

Send confirmation email to customer

Modal Component

Breadcrumb Navigation

Dashboard / Sales Orders / SO-24871

Progress & Loading States

Progress Bar

            Fulfillment progress72%
          

            Upload complete100%
          

Skeleton Loading

Avatar Components

ML

24px (sm)

ML

32px (default)

ML

48px (lg)

ML

DJ

KS

+4

Avatar Stack

Toast Notifications

        ⓘ Order SO-24871 saved
      

        ✓ Shipment confirmed successfully
      

        ✕ Failed to save. Try again.
      

        ⚠ Credit hold on customer account
      

■ Every interactive element must handle ALL defined states. Missing states cause inconsistent user experiences.

06 Table Standards Alignment, headers, width ratios, pagination, empty states

Column Alignment Rules

Order #	Date	Customer	Amount	Status
SO-24871	05/20/2026	Driscoll Foods	$48,320.00	Shipped
SO-24872	05/19/2026	Key Food Stores	$12,480.00	Pending
SO-24873	05/18/2026	C-Town Supermarkets	$6,150.00	Processing

Data Type	Alignment	Font	Width
Checkbox	Center	—	40px fixed
Document #	Left	IBM Plex Mono	120px
Date	Left	IBM Plex Mono	100px
Name / Entity	Left	Inter	flex (fill remaining)
Amount	Right	Inter, tabular-nums	120px right-aligned
Status badge	Center	IBM Plex Mono	140px
Actions	Right	—	160px right-aligned

Header & Cell Styling Rules

Table Header

IBM Plex Mono, 11px (text-xs), uppercase, letter-spacing .06em, graphite color, fog background, 2px cobalt bottom border.

Table Cell

Inter, 13px (text-sm), black color, 1px fog bottom border. Numbers use tabular-nums for alignment.

Row Height by Density

Density	Row Height	Font Size
Compact	36px	13px (text-sm)
Default (Comfortable)	44px	15px (text-base)
Spacious	56px	15px (text-base)

Zebra Striping

Off by Default

Do not use zebra striping by default. Use hover highlighting instead. Turn ON zebra striping only for tables exceeding 20 visible rows, using fog background on even rows.

Sortable Header Indicator

Sortable Columns

CUSTOMER ▴▾

AMOUNT ▴▾

DATE ▴▾

Inactive: steel arrows. Active (ascending): tufts up arrow. Active (descending): tufts down arrow.

Empty Table State

Order	Customer	Amount

No orders found

Try adjusting your filters or create a new order.

Pagination

Showing 1-10 of 247

‹

1

2

3

...

25

›

Sticky Header

Enable sticky table header (position: sticky; top: 42px) for any table with more than 10 visible rows. The 42px accounts for the topbar height.

■ Tables are the most-used component. Align numbers right, text left, status center. Always include pagination.

07 Icon Standards Sizes, colors, stroke width, alignment

Icon Size by Context

12px

Inline with text-xs labels

16px

Inline with body text, table cell icons

20px

Button icons, form field icons, nav item icons

24px

Section headers, card header icons

32px

Empty state illustrations, feature highlights

48px

Page-level empty states, onboarding

Icon Color Rules

Context	Default Color	Active/Hover Color
Navigation icons	slate (#6B7280)	cobalt (#092F64)
Action icons (edit, delete, view)	graphite (#4B5F7A)	cobalt (#092F64)
Status icons	Match status color: success/warning/error
Decorative icons	steel or slate	No hover change (decorative)

Stroke Width

1.5px for all icons. This matches the design system's 28x28 icon set. Never use 1px (too thin) or 2px (too heavy).

Icon + Text Alignment

Icon is vertically centered with the first line of adjacent text. Gap between icon and text is 8px (--sp-2). Never stack icons above text unless in a card or nav item.

Never: Mix filled and outlined icons in the same context. All GFS icons use outline (stroke) style exclusively.

■ Icons are always outlined (stroke), 1.5px weight. Size depends on context. Color follows the hierarchy.

08 Border & Divider Standards Weights, radius, shadows, divider patterns

When to Use: Borders vs Shadows vs Spacing

Borders

Cards, tables, form inputs, modals, portlets. Use when elements need defined boundaries at rest.

Shadows

Elevated cards (on hover), dropdowns, modals, toasts. Use only for elements that float above the page.

Spacing

Between sections, form groups, paragraphs. Use when elements are related but don't need a visible divider.

Border Weights

1px silver

Standard cards, table cells, inputs

2px cobalt

Section headers, active tabs, table header bottom

3px colored

Card accent top, active sidebar, status emphasis

Border Radius

0px

Tables, inputs

2px (radius-sm)

Buttons, badges, tags — DEFAULT

4px (radius-md)

Cards, modals, portlets

8px (radius-lg)

Pills, avatar — rare

50%

Avatars, status dots

Never: Use border-radius above 8px on rectangular elements. No rounded corners beyond the 8px maximum. This is the GFS sharp aesthetic.

Shadow Scale

shadow-sm

Inputs on focus

shadow-md

Card hover, dropdowns

shadow-lg

Modals, popovers

shadow-xl

Full-page overlays

Divider Patterns

Horizontal Rule

1px solid silver, full width, 24px margin top + bottom

Section Divider

2px solid cobalt, full width

List Divider

1px solid fog, indented to match content

■ Flat borders are the GFS default. Shadows are reserved for hover and floating elements only.

09 Content Writing Standards Empty states, errors, labels, placeholders, dialogs

Empty State Messages

Do

Title: "No orders found"

Description: "No sales orders match your current filters. Try adjusting the date range or status."

CTA: "Create Order"

Don't

Title: "Nothing here" or "Oops!"

Description: "It looks like there's nothing to show."

CTA: "Get Started" or "Click Here"

Error Messages

Type	Pattern	Example
Field validation	[Field] is required	Customer name is required
Field format	Enter a valid [type]	Enter a valid email address
System error	Something went wrong...	Something went wrong. Try again or contact support at (877) 728-5550.
Network error	Unable to connect...	Unable to connect. Check your connection and try again.
Permission	You don't have access...	You don't have access to this page. Contact your administrator.

Label Writing Rules

Element	Style	Font	Specimen
Form labels	Sentence case	IBM Plex Mono	Customer name
Table headers	UPPERCASE	IBM Plex Mono	CUSTOMER
Section titles	Title Case	Inter	Primary Information
KPI labels	UPPERCASE	IBM Plex Mono	TOTAL REVENUE
Button text	UPPERCASE	IBM Plex Mono
Tab text	UPPERCASE	IBM Plex Mono	OVERVIEW
Badge text	UPPERCASE	IBM Plex Mono	Shipped

Placeholder, Tooltip & Confirmation Text

Placeholder Text

Sentence case, descriptive. Example: "Search by customer name or order #..."

Tooltip Text

Sentence case, max 80 characters, no period at end. Example: "Click to export all visible rows as CSV"

Confirmation Dialog

Question format. Explain consequence. Primary action matches the verb.

Delete this order?

This will permanently remove SO-24871 and all line items. This cannot be undone.

Voice & Tone Rules

GFS Operational Tone

Your order SO-24871 shipped on May 20, 2026 via GFS Truck. Estimated delivery: May 22, 2026. Tracking available at the link below.

Direct, factual, action-oriented. No filler, no enthusiasm.

GFS Data Tone

Revenue: $1.2M (+12.3% YoY). Fill rate: 96.2% (target: 95.0%). 14 past-due invoices totaling $786K require action.

Numbers first, context second. Always include comparison or target.

Do Write

"Order shipped May 20, 2026."

"14 items require approval."

"Temperature exceeded 40°F at 14:32."

"Contact support at (877) 728-5550."

"Fill rate improved 2.1% this month."

Don't Write

"Great news! Your order is on its way!"

"Heads up — a few things need your attention."

"Yikes! Something seems off with the temperature."

"Don't hesitate to reach out to our team!"

"We're crushing it on fill rate this month!"

Approved Terminology

Use This	Not This	Context
Sales Order	SO, Sales Ord, Order	Full term in labels; SO-##### in references
Purchase Order	PO, Purchase Ord	Full term in labels; PO-##### in references
Invoice	Inv, Bill	Full term in labels; INV-##### in references
Customer	Client, Account, Buyer	Always "customer" in GFS context
Vendor	Supplier, Provider	Always "vendor" in GFS context
Ship date	Shipping date, Dispatch date	The date the order leaves the facility
Delivery date	Arrival date, ETA	The date the order reaches the customer
Fill rate	Fulfillment rate, Completion rate	% of ordered items actually shipped
Past due	Overdue, Late, Delinquent	Invoice that has passed its payment term
On hold	Paused, Stopped, Frozen	Order or account that requires manual review

Banned Words & Phrases

Never: "synergy", "leverage", "circle back", "deep dive", "moving forward", "at the end of the day", "low-hanging fruit", "paradigm shift"

Never: "Oops!", "Whoops!", "Uh oh", "Yikes", or any casual/cute exclamation in operational UI.

Never: "Click here", "Learn more", "Get started" as standalone link/button text. Always specify the action.

■ Be specific, not clever. Every label, error, and empty state has exactly one correct pattern.

10 Motion & Animation Standards Duration, easing, which animation for which action

Which Animation for Which Action

Action	Animation	Duration	Easing
Page navigation	None (instant)	—	—
Tab/panel switch	Instant (no animation)	—	—
Modal open	Fade in + scale from 0.95	200ms	ease-out
Modal close	Fade out	150ms	ease-in
Dropdown open	Slide down	200ms	ease-out
Toast appear	Slide in from right	300ms	spring
Toast dismiss	Fade out	200ms	ease-out
Card hover	translateY(-2px)	200ms	ease-out
Button press	scale(0.98)	100ms	ease-in
Accordion expand	Height auto	300ms	ease-out
Skeleton shimmer	Background position	1.5s infinite	linear
Spinner	Rotation	600ms infinite	linear
Progress bar	Width transition	600ms	ease-out

Duration Rules

100-150ms

Micro-interactions: button press, toggle switch, focus ring.

200ms

Standard transitions: hover states, focus, color changes.

300-400ms

Medium transitions: accordion open, slide panels, drawers.

600ms

Slow transitions: progress bars, skeleton states.

When NOT to Animate

Never: Data updates (table sorts, filter results) — these should be instant, not animated.

Never: Form validation (error states appear instantly, no fade or slide).

Never: Page loads (no entrance animations on portals — content should be immediate).

Never: Animate width, height, top, left, or margin. ONLY animate transform and opacity for performance.

Reduced Motion

Mandatory: Respect prefers-reduced-motion

ALWAYS wrap animations in @media (prefers-reduced-motion: no-preference). Users who have enabled reduced motion in their OS settings should see no animations. The shared.css already includes a global rule that disables all animations when reduced motion is preferred.

Easing Functions Reference

--ease-out: cubic-bezier(0.16, 1, 0.3, 1)

--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1)

--spring: cubic-bezier(0.34, 1.56, 0.64, 1)

■ User-initiated actions feel instant. System-initiated actions can animate. Only transform and opacity.

11 Dark Mode Rules Token swap table, testing checklist, common mistakes

Complete Token Swap Table

Token	Light Value	Dark Value
--cobalt	#092F64	#93BFEF
--navy	#1A5799	#468BE6
--tufts	#468BE6	#6BA3ED
--jordy	#93BFEF	#1A5799
--alice	#E9F5FF	#0A1929
--ice	#F4F9FF	#0D1F33
--black	#1F1F1F	#F0F2F5
--graphite	#4B5F7A	#9CA3AF
--slate	#6B7280	#6B7280 (same)
--steel	#9CA3AF	#4B5F7A
--silver	#D9E1EA	#2D2D2D
--fog	#F0F2F5	#1A1A1A
--white	#FFFFFF	#111111
--success	#0F766E	#34D399
--warning	#B45309	#FBBF24
--error	#DC2626	#F87171

Dark Mode Rules

Shadows Get Stronger

In dark mode, shadows use higher opacity (0.3-0.6 vs 0.06-0.16 in light). They become more prominent, not less.

Borders Get Subtler

Border contrast against background decreases. Silver maps to #2D2D2D, which is close to the dark background.

Status Colors Get Brighter

Success (#0F766E to #34D399), warning (#B45309 to #FBBF24), error (#DC2626 to #F87171). Higher saturation for readability.

Text Hierarchy Stays Same

Primary text is still the most prominent. Secondary is still dimmer. Tertiary is still the dimmest. The relative contrast ratios are preserved.

Never: Use opacity to create dark mode colors. Always swap tokens with explicit hex values.

Never: Modify images or photos for dark mode. Charts should get a slight brightness boost only.

Dark Mode Testing Checklist

All text meets 4.5:1 contrast ratio against its background
Status badges remain readable and distinguishable
Focus rings (tufts) are visible against dark backgrounds
Border colors are visible but not harsh
Hover states produce a visible change
Active/selected states are clearly distinguishable from default
Form inputs have clear boundaries
Charts and data visualizations remain legible
Skeleton loading states are visible
No hardcoded hex values override the CSS variable swaps

Common Mistakes

Mistake	Wrong	Right
Hardcoded text color	color: #1F1F1F	color: var(--black)
Hardcoded background	background: #FFFFFF	background: var(--white)
Opacity-based dark	color: rgba(0,0,0,.8)	color: var(--graphite)
Static border color	border: 1px solid #D9E1EA	border: 1px solid var(--silver)
Using filter:invert	filter: invert(1)	Use token swap in [data-theme="dark"]

■ Dark mode is automatic via CSS variable swap on [data-theme="dark"]. Never hardcode colors.

12 Print Rules @media print specs, page layout, company header

@media print Specifications

Hide on Print

Element	Reason
Topbar / navigation	Not needed on paper
Buttons / interactive controls	Non-functional on paper
Search inputs	Non-functional on paper
Footer links	Non-clickable on paper
Scroll nav / back-to-top	Screen-only navigation
Theme toggle	Screen-only control

Print Dimensions

Property	Value
Page margins	0.75in all sides
Body font	11pt
Headings	14pt
Labels	9pt
Colors	Black/white except status badges
Table header	Repeat on every page
Table rows	page-break-inside: avoid

Company Header (Always Print)

Global Food Solutions, Inc. | 131 Heartland Blvd, Edgewood, NY 11717 | (877) 728-5550

Page Numbers

Bottom-center, "Page X of Y"

Use CSS counters and @page rules to insert page numbers in the format "Page 1 of 5" centered at the bottom of every printed page.

Print CSS Snippet

@media print {
  .topbar, .scroll-nav, .toc, .back-to-top,
  .topbar-btn, button, .btn { display: none; }
  body { font-size: 11pt; color: #000; background: #fff; }
  h2, h3 { font-size: 14pt; }
  .label, .form-label { font-size: 9pt; }
  @page { margin: 0.75in; }
  thead { display: table-header-group; }
  tr { page-break-inside: avoid; }
  .badge { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
}

■ Every printed page includes the company header. Status badges keep their colors. Everything else is black and white.

13 Responsive Breakpoints What changes at every breakpoint

Breakpoint Decision Table

Breakpoint	Card Grids	KPI Rows	Tables	Sidebar	Forms
1280px+	4 columns	4 columns	Full width	Full (220px)	2 columns
1024px	3 columns	2 columns	Full width	Collapsed (icons)	2 columns
768px	2 columns	2 columns	Horizontal scroll	Hamburger drawer	1 column
550px	1 column	1 column	Horizontal scroll	Bottom nav	1 column

Additional Breakpoint Behaviors

Component	Desktop (1280+)	Tablet (768-1024)	Mobile (<768)
Modals	Centered, max-width 400px	Centered, max-width 400px	Full-screen
Font sizes	No change	No change	No change (already responsive)
Touch targets	32px minimum	44px minimum	48px minimum
Hero title	text-7xl (96px)	text-5xl (56px)	text-4xl (40px)
Page padding	32px (--sp-8)	24px (--sp-6)	12px (--sp-3)
Scroll nav dots	Visible	Visible	Hidden
Section meta	Visible	Visible	Hidden

Never: Stack table columns on mobile. Tables must always use horizontal scroll wrapper. Data tables are meant to be read in row format.

Breakpoint Visualization

550px

768px

1024px

1280px

        Small Mobile
        Mobile
        Tablet
        Desktop
        Wide
      

■ Mobile-first CSS. Test all breakpoints before deployment. Tables always scroll horizontally, never stack.

14 Naming Conventions CSS classes, JS functions, HTML IDs, file names, NEVER rules

CSS Classes

Lowercase, Hyphenated

All CSS classes use lowercase letters with hyphens as separators.

.form-group .kpi-val .btn-primary .badge-green .demo-table .s-head .hero-title .sidebar-nav-item

Prefix Rules

Prefix	Scope	Example
.ns-	NetSuite-specific components	.ns-portlet, .ns-saved-search
.gfs-	Brand-specific overrides	.gfs-watermark, .gfs-barcode
(none)	Shared / universal components	.btn, .input, .badge, .kpi

JavaScript Functions

camelCase, Verb-First

All JS functions start with a verb describing the action.

getValue() handleClick() renderTable() validateForm() fetchOrders() setDensity() toggleTheme() searchSections() formatCurrency() parseDate() showToast() closeModal()

HTML IDs

camelCase

HTML IDs use camelCase. IDs are for JavaScript targeting only, never for CSS styling.

id="mainContent" id="dataTable" id="searchInput" id="densityDemo" id="backToTop" id="readingProgress"

File Names

kebab-case

All file names use lowercase with hyphens.

portal-sales-orders.html netsuite-starter.html shared.css design-spec.html tokens.json print.css

Data Attributes

data-sort-col="amount" data-filter-status="active" data-page="3" data-row-id="24871" data-density="compact" data-theme="dark"

CSS Custom Properties Hierarchy

Layer	Purpose	Examples
Primitive	Raw values, the source of truth	--cobalt, --sp-4, --text-sm
Semantic	Purpose-based aliases	--primary, --background, --border
Component	Component-specific tokens	--sidebar-background, --card-accent

NEVER Rules

Never: Use inline styles for repeating patterns. If you write the same style 3+ times, make a class.

Never: Use !important. Fix specificity by adjusting selector order instead.

Never: Use ID selectors for styling. IDs are for JavaScript only. Use class selectors for CSS.

Never: Hardcode hex colors. Always use CSS variable tokens (--cobalt, --silver, etc.).

Quick Reference Table

Context	Convention	Example
CSS classes	lowercase-hyphenated	.form-group, .btn-primary, .kpi-val
CSS variables (primitive)	--lowercase	--cobalt, --sp-4, --text-sm
CSS variables (semantic)	--lowercase-hyphenated	--primary, --sidebar-background
JavaScript functions	camelCase verb-first	getValue(), handleClick()
JavaScript constants	UPPER_SNAKE_CASE	MAX_ROWS, API_BASE_URL
HTML IDs	camelCase	mainContent, searchInput
HTML data attributes	data-context-property	data-sort-col, data-filter-status
File names	kebab-case	portal-sales-orders.html
Section IDs	s-kebab-case	s-typography, s-color, s-tables
Image files	kebab-case with descriptor	logo-dark-bg.svg, hero-globe.png

■ Naming is consistency. CSS: hyphen-case. JS: camelCase. Files: kebab-case. IDs: camelCase. No exceptions.

15 Pre-Flight Checklist Verify before every deployment

Every GFS page must pass this checklist before deployment. No exceptions.

Infrastructure

shared.css linked in <head>
print.css linked with media="print"
Google Fonts linked (Inter + IBM Plex Mono) with preconnect
Topbar present with live dot, Hub link, search, version, dark mode toggle
searchSections() function in script block
toggleTheme() function in script block
Footer with "Back to Hub" link and company address
Skip-to-content link for accessibility
Back-to-top button with scroll listener
Reading progress bar (for long pages)

Brand Identity

Address: 131 Heartland Blvd, Edgewood, NY 11717
Phone: (877) 728-5550
Company: Global Food Solutions, Inc.
CEO: Michael Levine
No Chicago references or (312) area code
No paid font references (Sohne Breit, Neue Haas Grotesk)
At least one brand DNA element (dot-matrix, brackets, barcode, grid)
Hermitage, PA facility mentioned where relevant

Technical Quality

All colors use CSS variables, no hardcoded hex
All section IDs are unique
Dark mode tested and functional
Responsive at 1280, 1024, 768, and 550 breakpoints
No console errors
Images have alt text (if applicable)
Focus states visible for all interactive elements
Page loads under 3 seconds on 3G connection
No horizontal scroll at any viewport width
Print layout tested (Ctrl+P preview)

Content Quality

No selling language or superlatives
No emojis in operational UI
All numbers follow the formatting specification
All dates follow MM/DD/YYYY (tables) or Month Day, Year (prose)
All statuses use the approved badge color mapping
Empty states have specific title, description, and CTA
Error messages follow the approved patterns
No placeholder/lorem ipsum text in production

Prohibited Patterns

Never: Use warm colors, earthy palettes, or rustic textures. GFS is cold-chain, precision, blue-tech.

Never: Use shadows on cards at rest. Flat borders only. Shadows appear on hover or for floating elements.

Never: Use border-radius above 8px on rectangular elements. The GFS aesthetic is sharp and precise.

Never: Mix font families arbitrarily. Inter for readable text, IBM Plex Mono for system/data text.

Never: Use inline styles for repeating patterns. If you write the same style 3+ times, create a class.

Never: Use !important. Fix specificity by adjusting selector order.

Never: Expose GFS internal security details, system architecture, or employee PII in any portal.

■ This checklist is mandatory. A page that fails any item is not ready for deployment.

16 Complete Token Reference Every CSS variable in the design system

Color Tokens

Token	Light	Dark	Usage
--cobalt	#092F64	#93BFEF	Primary brand, headings, CTAs
--navy	#1A5799	#468BE6	Hover states, secondary emphasis
--tufts	#468BE6	#6BA3ED	Interactive elements, links, focus
--jordy	#93BFEF	#1A5799	Accents, chart secondary
--alice	#E9F5FF	#0A1929	Highlighted backgrounds
--ice	#F4F9FF	#0D1F33	Subtle backgrounds, hover
--midnight	#051B3A	#F4F9FF	Deep dark brand contexts
--black	#1F1F1F	#F0F2F5	Primary text
--charcoal	#2D2D2D	#E5E7EB	Toast backgrounds
--graphite	#4B5F7A	#9CA3AF	Secondary text
--slate	#6B7280	#6B7280	Tertiary text, labels
--steel	#9CA3AF	#4B5F7A	Placeholder, disabled text
--silver	#D9E1EA	#2D2D2D	Borders, dividers
--fog	#F0F2F5	#1A1A1A	Muted backgrounds
--white	#FFFFFF	#111111	Page background, card surface
--success	#0F766E	#34D399	Positive status
--success-bg	#F0FDF4	#0A1F15	Success alert background
--warning	#B45309	#FBBF24	Caution status
--warning-bg	#FFFBEB	#1F1A0A	Warning alert background
--error	#DC2626	#F87171	Negative status
--error-bg	#FEF2F2	#1F0A0A	Error alert background
--info	#1A5799	#6BA3ED	Informational status
--info-bg	#E9F5FF	#0A1929	Info alert background

Spacing Tokens

Token	Value	Primary Usage
--sp-1	4px	Minimum spacing, inline gaps
--sp-2	8px	Icon-text gaps, tight padding
--sp-3	12px	Table cell padding, button padding
--sp-4	16px	Default padding, card gaps
--sp-5	20px	Card padding, form spacing
--sp-6	24px	Section gaps, grid gaps
--sp-8	32px	Major section breaks, page padding
--sp-10	40px	Large padding contexts
--sp-12	48px	Hero padding, empty state padding
--sp-16	64px	Extra-large contexts
--sp-20	80px	Rare, very large spacing
--sp-24	96px	Maximum spacing token

Typography Tokens

Token	Value	Usage
--text-xs	11px	Labels, badges, system meta
--text-sm	13px	Secondary body, table cells
--text-base	15px	Primary body text
--text-lg	17px	Card titles, sub-headings
--text-xl	20px	Section sub-titles
--text-2xl	24px	Section titles
--text-3xl	32px	KPI values, hero stats
--text-4xl	40px	Page hero titles
--text-5xl	56px	Large display (tablet hero)
--text-6xl	72px	Extra large display
--text-7xl	96px	Hero title (desktop)

Radius, Shadow & Motion Tokens

Token	Value	Usage
--radius-sm	2px	Buttons, badges, tags (default)
--radius-md	4px	Cards, modals
--radius-lg	8px	Pills, rare rounded elements
--shadow-sm	0 1px 2px rgba(9,47,100,0.06)	Input focus
--shadow-md	0 2px 8px rgba(9,47,100,0.08)	Card hover, dropdowns
--shadow-lg	0 8px 24px rgba(9,47,100,0.12)	Modals, popovers
--shadow-xl	0 16px 48px rgba(9,47,100,0.16)	Full-page overlays
--ease-out	cubic-bezier(0.16,1,0.3,1)	Standard exit easing
--ease-in-out	cubic-bezier(0.65,0,0.35,1)	Symmetric transitions
--spring	cubic-bezier(0.34,1.56,0.64,1)	Bouncy entrances (toasts)
--dur-fast	120ms	Micro-interactions
--dur-base	200ms	Standard transitions
--dur-slow	400ms	Medium transitions
--dur-slower	600ms	Slow transitions

Semantic Tokens

Token	Maps To	Usage
--primary	var(--cobalt)	Primary actions, brand elements
--primary-foreground	#FFFFFF	Text on primary backgrounds
--background	var(--white)	Page background
--foreground	var(--black)	Page text
--card	var(--white)	Card surfaces
--card-foreground	var(--black)	Card text
--muted	var(--fog)	Muted backgrounds
--muted-foreground	var(--slate)	Muted text
--accent	var(--alice)	Accent backgrounds
--accent-foreground	var(--cobalt)	Accent text
--destructive	var(--error)	Destructive actions
--border	var(--silver)	All borders
--input	var(--silver)	Input borders
--ring	var(--tufts)	Focus rings
--sidebar-background	var(--white)	Sidebar surface
--sidebar-foreground	var(--graphite)	Sidebar text
--sidebar-primary	var(--cobalt)	Active sidebar items
--sidebar-accent	var(--ice)	Sidebar hover backgrounds
--sidebar-border	var(--silver)	Sidebar borders
--sidebar-ring	var(--tufts)	Sidebar focus rings
--chart-1	var(--cobalt)	Chart primary series
--chart-2	var(--navy)	Chart series 2
--chart-3	var(--tufts)	Chart series 3
--chart-4	var(--jordy)	Chart series 4
--chart-5	var(--alice)	Chart series 5

■ These tokens are the single source of truth. Never create ad-hoc values. If a token doesn't exist, it's not in the system.