# Warm Editorial

Status: Ready  
Version: 1.0.0  
Source study: Pondo, a private household-finance PWA  
Portable artifact: Formwork `/designs/warm-editorial`

## The short version

Warm Editorial treats useful software like a well-edited household ledger. Warm cream carries the page, one ink-colored surface anchors navigation, white and sand separate working areas, and green marks decisions. Newsreader gives titles a human editorial voice; Geist keeps controls and figures precise. Panels are square, hierarchy is spacious, and the interface explains what the data means before it decorates it.

Use this direction for:

- personal finance and household planning;
- private records and trusted personal tools;
- calm dashboards with a small number of important decisions;
- data-heavy products that benefit from reflection rather than urgency;
- responsive web apps that must feel intentional on both phone and desktop.

Do not use it unchanged for:

- trading terminals or real-time monitoring walls;
- dense operations consoles that must show many simultaneous statuses;
- playful, juvenile, or heavily gamified products;
- expressive campaign sites where motion and imagery are the primary content;
- systems that require a large categorical palette on every screen.

## Provenance and evidence

This guide was extracted from Pondo's current implementation, canonical design documentation, responsive components, operational states, and tests. “Warm Editorial” is Formwork's portable name; it does not appear as a product label inside Pondo.

Pondo's repository describes three internal visual references. The closest reference supplied the cream canvas and dark navigation structure; the others informed mobile navigation, compact controls, desktop breathing room, and single-accent restraint. Original source URLs and creator names are not recorded, so this guide does not invent an attribution or reproduce any reference asset.

Pondo's independently implemented adaptations include privacy-aware balances, personal-versus-household scope, adaptive rail and bottom navigation, stable edit sheets, and CSS-native financial reports.

## Design thesis

The system should feel private, calm, capable, family-aware, and clear. It should not look like a bank, a trading product, a corporate admin template, or a game.

Five rules make that feeling repeatable:

1. **Content before chrome.** Put the title, scope, important number, and next decision before ornamental structure.
2. **One dark anchor.** Use ink for navigation or another single structural surface. Do not add a second dark hero card merely to create drama.
3. **Warmth through tone and type.** Cream, sand, rules, and Newsreader create identity. Gradients, blobs, and decorative flourishes are unnecessary.
4. **Accent by meaning.** Green means action, active state, focus, progress, or privacy. It is not a background wash.
5. **Explain the data.** A chart or metric should answer a household question and include a text takeaway or accessible value.

## Color system

| Token | Value | Role |
| --- | --- | --- |
| Ink | `#1F1B16` | Primary text and the only dark structural surface |
| Green | `#1F4B3D` | Primary action, active state, focus, progress, privacy |
| Green soft | `#2F5E4F` | Green hover and secondary emphasis |
| Cream | `#F7F4EC` | Page and PWA background |
| Sand | `#F0EBDD` | Secondary surface, icon chip, track, skeleton |
| Surface | `#FFFFFF` | Working panels, forms, overlays |
| Slate | `#5C574C` | Secondary copy; documented at 6.5:1 on cream in Pondo's guide |
| Border | `#DED5BE` | Warm hairline, separator, input boundary |
| Gold | `#D99A2B` | Fill-only secondary accent; not small text on cream |
| Clay | `#A6491F` | Expense, warning, badge, warm emphasis |
| Danger | `#B4231F` | Destructive action and error semantics |

### Surface ladder

Use the tonal sequence deliberately:

1. Cream is the page field.
2. Sand groups secondary or contextual material.
3. White is a working surface.
4. Ink is a structural anchor, not another card color.

A panel normally uses either a white/sand tonal change or a border. Avoid stacking a bordered white card inside another bordered white card.

### Safe combinations

- Ink on cream, sand, or white for primary copy.
- Slate on cream or white for supporting copy.
- Cream or white on ink for navigation.
- White on green for primary actions.
- Ink on gold; do not use gold as small text on cream.
- Clay or danger must be paired with an icon, label, or explanatory copy when they signal status.

Never rely on green versus clay alone to explain meaning.

## Typography

### Families

- **Newsreader**, upright weights 400–600: page titles, section headings, card titles, and occasional display statements.
- **Geist**: body copy, controls, labels, metadata, and all monetary figures.
- **Geist Mono**: optional compact technical metadata. It is not a dominant application face.

If these exact families cannot be used, preserve the relationship: a warm, readable editorial serif for display and a compact neutral sans with strong numerals for utility.

### Scale

| Role | Typical size | Notes |
| --- | --- | --- |
| Hero balance | 44–56 px | Geist, semibold, tight tracking, tabular figures |
| Page display | 36–48 px | Newsreader 500, tight tracking, short lines |
| Section title | 20–24 px | Newsreader 500 |
| Supporting stat | 28–36 px | Geist semibold |
| Body | 14–16 px | Geist, 1.5–1.7 line height |
| Metadata | 12–13 px | Geist medium; never the only carrier of critical meaning |

### Money and data

- Store money as integer minor units. Formatting is application logic, not a CSS concern.
- Use `font-variant-numeric: tabular-nums slashed-zero` for aligned or changing values.
- Use the sans face for large balances; the display serif is for language, not dense figures.
- Preserve the value's currency. Do not add unlike currencies into one total without an explicit conversion model.
- Keep amounts visible in rows; truncate long names before truncating financial values.

## Spacing and composition

Use a 4 px base rhythm. The most useful steps are 8, 12, 16, 20, 24, 32, 40, and 48 px.

### Page composition

- On mobile, use 16–24 px horizontal page padding and 24–32 px between major sections.
- On desktop, place content beside a 256 px navigation rail and cap the content region around 1152 px.
- Keep the page title row stable: title and description on the left, one primary utility on the right when needed, then a full-width hairline.
- Align card edges, dividers, and actions to a small number of shared tracks.
- Do not fill ultrawide monitors simply because space exists.

### Density

- A standard row should remain comfortable at roughly 56–72 px.
- Use divided rows for changing records and comparison.
- Use panels for distinct jobs, not for every label/value pair.
- Reserve 24–32 px panel padding for editorial or decision-heavy surfaces; dense mobile panels may use 16–20 px.
- Give the most important number enough space to be read without scrolling on common phone heights.

## Shape, borders, and elevation

- Standard card, panel, input, and button radius: `0`.
- Use a full pill only when the control's behavior is inherently pill-like, such as a compact binary toggle or avatar.
- Standard boundary: `1px solid #DED5BE`.
- Permanent content surfaces should not need a shadow.
- Transient sheets, dialogs, popovers, and menus may use one restrained warm shadow.
- Never apply a border and a strong shadow to the same permanent card.
- Avoid decorative corners, floating badges, and detached icon tiles that do not explain a real state.

## Iconography

- Use simple line icons in the 16–20 px range.
- Pair unfamiliar icons with text.
- Use icons to improve scanning, not to create decoration between headings.
- Keep icon chips square and tonal: sand with green is the default light treatment.
- Hide purely decorative icons from assistive technology.

## Responsive system

The hierarchy stays stable while navigation and editing behavior change.

### Stable at every width

1. Page identity.
2. Scope or privacy context.
3. Most important value or decision.
4. One primary next action.
5. Supporting records and explanations.

### Desktop

- Use a sticky ink rail around 256 px wide.
- Keep the active destination visible through tone and text weight, with `aria-current="page"` in implementation.
- Use two columns only when each panel still has a distinct job.
- A main/supporting split may use approximately 1.15fr/0.85fr.
- Reports may use a two-column supporting grid after a full-width primary chart.

### Mobile

- Replace the rail with a five-position ink bottom navigation.
- Keep the primary creation action in the center and make it visually distinct without becoming circular by default.
- Reserve content padding for the fixed navigation and device safe area.
- Stack panels, keep amounts aligned to the trailing edge, and move secondary row actions into a stable menu or sheet.
- Use 16 px form text to avoid automatic mobile browser zoom.
- Edit in a full-height sheet that accounts for the virtual keyboard and safe-area inset.

### Long and dense content

- Truncate long entity names but retain accessible labels and visible amounts.
- Convert tables into divided rows before allowing horizontal scrolling.
- Keep filter controls wrap-safe and let a primary action become full-width at narrow sizes.
- Test at a 390 px viewport and at the exact width where the navigation changes.

## Motion

Motion should confirm state, preserve orientation, or make an overlay understandable.

- Color, underline, focus, and route-pending feedback: roughly 160 ms.
- Sheets and dialogs: roughly 200 ms.
- A sheet may translate from the bottom on mobile and from the inline edge on wider screens.
- A route transition may reveal a delayed 2 px pending rule instead of a large blocking spinner.
- Skeletons may pulse only when motion is allowed.
- Keep balances stable; do not count numbers up or animate their width.
- Do not add looping decoration, parallax, slow reveals, or layout-shifting hover motion.

Provide a `prefers-reduced-motion: reduce` fallback that effectively removes animation and transitions. Pondo currently applies this explicitly to skeletons; an adopting project should apply it consistently to the full pack.

## Component language

### Page header

Purpose: establish the job of the page before controls or cards.

- Newsreader title, one-line or short description, optional action.
- Divider belongs to the header so every page starts from the same baseline.
- On narrow screens the action stacks and may fill the available width.

States: with or without description; with or without action; stacked or horizontal.

### Primary and secondary actions

- One green primary action per decision surface.
- Primary buttons use white on green and normally meet a 44 px minimum height on touch surfaces.
- Secondary buttons use white or transparent surfaces with a warm border.
- Quiet actions may use text and underline behavior.
- Destructive actions use danger color and always require clear labeling; irreversible work should require confirmation.

Every control needs visible hover, focus-visible, disabled, and pending behavior where applicable. Pending labels should remain specific, such as “Saving…” or “Exporting…”.

### Segmented control

- Use for two to four mutually exclusive views, not as general navigation.
- Put options inside one square bordered group.
- Active: green surface with white text.
- Inactive: white surface with slate text and sand hover.
- Use buttons with `aria-pressed`; do not communicate selection by color alone in assistive output.

### Financial summary

- Put scope/privacy before the value.
- Use a large sans-serif amount with tabular figures.
- List constituent accounts as divided rows.
- Show total/spendable as an explicit mode, not an unexplained alternative number.
- In the empty state, explain privacy and point to the first real action.

### Record row

- Primary name, compact metadata, and trailing amount.
- Use a lock label/icon for personal records when mixed with household data.
- Income may use green; transfers stay neutral; expenses remain ink unless warning meaning is required.
- Color is supplemental. Prefixes, labels, and metadata carry the meaning.

### Progress

- Sand track, green fill, text percentage or value.
- Clamp visual progress to 0–100 while preserving the real numeric context in text.
- Use a semantic progressbar with a label, numeric value, and readable value text.

### Empty state

An empty state must answer three questions:

1. What is absent?
2. What will appear here?
3. What is the real next action?

Use the same component for empty and populated surfaces rather than maintaining a disconnected onboarding page.

### Loading

- Match the shape of the destination: page header, metrics, rows, or report panels.
- Put `role="status"` and `aria-busy="true"` on the loading region.
- Hide decorative bones from assistive technology and include one screen-reader label.
- Stop pulsing under reduced motion.

### Error and recovery

- Preserve the page or shell when possible.
- State whether data changed.
- Offer one clear recovery action.
- Do not expose runtime, database, or authentication internals to the user.

### Sheets, dialogs, and menus

- Create and edit in a stable sheet rather than expanding a row inline.
- Protect dirty forms with a discard confirmation.
- Use focus management, Escape behavior, semantic titles/descriptions, and keyboard navigation from an accessible primitive.
- On mobile, account for the virtual keyboard and device safe area.
- Keep destructive choices visually and verbally distinct.

## Applied product patterns

### Personal dashboard

Lead with personal scope, the balance mode, and the most important total. Follow with household context, monthly cash flow, upcoming bills, saving goals, and recent activity. Privacy remains visible at both shell and row level.

### Reports

Use text plus CSS bars for modest datasets. Each panel states a conclusion—such as which category leads spending—before presenting the bars. Keep exact values in text so the chart is not the only representation.

### Savings

Place the goal name and progress first, contribution history second, and editing actions in a stable sheet. A goal is about what money is for; an account is about where it sits. Keep that distinction in labels and empty-state copy.

### Accounts and reconciliation

Separate personal and household groups explicitly. Keep balance and scope visible in every row. Reconciliation is a focused workflow, not another dashboard card.

### Authentication and setup

Use a focused single-column surface. Keep the brand and editorial heading, but remove the full signed-in shell. One job, one primary action, and direct recovery copy.

## Accessibility requirements

- Target WCAG 2.2 AA.
- Maintain visible focus at all times; use a 2 px green ring or border with a visible offset on light surfaces.
- Keep primary touch controls at least 44 px high and ensure icon-only controls have accessible names.
- Use semantic headings, landmarks, lists, buttons, links, dialogs, and progress bars.
- Use `aria-current`, `aria-pressed`, `aria-expanded`, `aria-controls`, `aria-invalid`, and `aria-busy` only where their behaviors are real.
- Pair every error with specific text and the relevant field or recovery action.
- Never use color as the only indicator of scope, status, trend, or selection.
- Keep charts understandable through text labels and values.
- Verify keyboard traversal and focus return for every overlay.
- Test zoom, 390 px mobile overflow, safe areas, and reduced motion manually.

Pondo's current automated evidence includes a credentialed Playwright core-route smoke test, a critical-impact axe scan, and a 390 px overflow assertion. That is useful evidence, not a substitute for a full manual accessibility audit.

## Implementation notes

Pondo currently uses Next.js App Router, React, TypeScript, Tailwind CSS v4, semantic CSS variables, shadcn/Base UI primitives, Lucide icons, React Hook Form, Zod, TanStack Query, Supabase, and a service worker.

Important implementation choices:

- React Server Components are the default; client components are reserved for real interaction.
- Route data is fetched in parallel where possible.
- Private-route prefetch occurs on focus, pointer, or touch intent instead of automatically warming every link.
- Query defaults use a 60-second stale time, disable window-focus refetch, and allow reconnect refetch.
- Reports use CSS bars rather than a chart library.
- Money formatting is centralized and begins with integer minor units.
- Route fallbacks preserve the visual shape of each page.

None of these libraries are required to adopt the visual direction. The portable layer is the token, composition, state, and accessibility contract.

## Portable tokens

The published `tokens.css` scopes every variable under `.warm-editorial-pack`. Do not move pack colors onto global `:root` unless this direction owns the entire application.

```html
<main class="warm-editorial-pack">
  <!-- application or feature surface -->
</main>
```

Self-host Newsreader and Geist, or change `--we-font-display` and `--we-font-body` to approved local equivalents.

## Adoption sequence

1. Copy `tokens.css` and wrap the intended surface with `.warm-editorial-pack`.
2. Load Newsreader and Geist or define equivalent local font tokens.
3. Build the page field, one ink navigation anchor, and the shared page header before individual cards.
4. Establish money/data formatting, scope labels, focus behavior, and 44 px primary controls.
5. Copy only the primitives you need from `components.tsx` and import `components.css`.
6. Adapt domain components from the documented reference patterns rather than copying Pondo's data, auth, routing, or Supabase imports.
7. Implement loading, empty, error, disabled, destructive, and reduced-motion behavior before calling a workflow complete.
8. Test at narrow mobile, the navigation breakpoint, standard desktop, keyboard-only input, zoom, and reduced motion.

## Copyable components

The public source includes:

- `EditorialPageHeader`;
- `EditorialEmptyState`;
- `EditorialProgress`;
- `EditorialSegmentedControl`.

They are strictly typed and depend only on React plus the two published CSS files. The segmented control is controlled; the adopting application owns its state.

This source is **copyable**, not one-command installable. Formwork does not yet generate or validate shadcn registry JSON.

## Avoid

- cool gray or blue-dominant page surfaces;
- green-tinted page washes or several competing green panels;
- gradients, glowing blobs, and ornamental charts;
- nested cards and grids of identical KPI tiles;
- rounding every surface;
- using the display serif for long body text, controls, or dense money columns;
- a second dark hero card inside an already dark-anchored shell;
- hiding privacy or scope in settings only;
- inline edit expansions that move surrounding rows;
- icon-only meaning, color-only status, and unlabeled charts;
- fake precision, count-up balances, or reward-loop motion;
- claiming installability before a registry artifact actually exists.

## Known limits

- The original visual reference URLs and authors are not recorded.
- Pondo's dark mode tokens are provisional and are not part of this ready direction.
- The source repository has no committed visual-regression baseline.
- The current reduced-motion implementation is strongest on skeletons and should be broadened when adopting the full system.
- Pondo's generic scaffolded button primitive includes sizes below 44 px; product-primary touch actions generally use explicit 44 px sizing. Audit controls in context.
- Automated accessibility evidence does not replace manual WCAG validation.

## Artifact map

- Raw guide: `/designs/warm-editorial/DESIGN.md`
- Portable tokens: `/designs/warm-editorial/tokens.css`
- Component styles: `/designs/warm-editorial/components.css`
- Copyable React source: `/designs/warm-editorial/components.tsx`
- Canonical repository source: `registry/warm-editorial/`
- Registry status: copyable source only; generated registry JSON is not available