The Polis Project / Design Systems Design

A working design system for evidence, care and public memory.

The Polis Project needs a system that can hold difficult work without making it feel distant. This page lays out the foundations, components and patterns I would use to support reporting, research, archives and careful review.

Explore the system View token model See visuals

Polis system blueprintDesign system map

System coverage

A compact view of the pieces that need to work together before this becomes a usable system.

06core values translated into visual and interaction rules

03token layers: primitive, semantic and component

08component and pattern families for product, editorial and assisted review

05documentation surfaces for adoption, QA and governance

FoundationBrand, accessibility, content, motion, layoutCore

ProductInputs, navigation, feedback, data displayUI

TrustSources, citations, evidence, assisted reviewRequired

Design system foundations

A design system for public-interest work.

The system should make hard material easier to read, check and publish. It should help a small team move quickly without losing the discipline that public-interest work depends on.

Company

The Polis Project

Company name is safe to show as workplace context.

My role

Product designer

Defined the use case, workflow, information architecture and product narrative.

Timeline

6 weeks

From problem framing through design systems design and output structure.

Outcome

10 hours saved weekly

Reduced web design time by 6 hours and digital asset design time by 4 hours each week.

Brand direction

The visual direction should feel serious, direct and global. It needs urgency, but not panic; solidarity, but not saviorism; clarity, without flattening the people and places behind the work.

ResearchDeep inquiry, field context and defensible source practice.

ReportageEditorial clarity for stories, reports and public records.

ResistanceVisual urgency grounded in dignity and accountability.

TrustTransparent systems for authorship, review and correction.

EvidenceEvery claim should connect back to inspectable support.

AccessibilityThe system must work across ability, device and context.

Typography anchors

The type system gives the project a clear editorial voice: strong headlines, readable body copy and quiet metadata for citations, captions and source context.

Role	Typeface	Purpose
Display	Akhand 800	Strong editorial presence
Body	Anek 400/500	Readable product and article text
Metadata	Noto Serif Thin	Citations, captions and source context

Token architecture

Primitive values become editorial decisions.

Tokens keep the system honest. Instead of repeating one-off colors or spacing, each value earns a role: surface, warning, citation, evidence, focus, chart or component state.

01

Primitive

Raw color, type, spacing, border, radius, motion and opacity values.

02

Semantic

Role-based tokens for surfaces, text, evidence, warnings, focus and chart states.

03

Component

Button, field, card, table, chart, citation and source drawer mappings.

04

Themes

Light, dark, high-contrast, brand and enterprise modes override semantics.

05

Code

CSS variables, Tailwind preset, React packages and Style Dictionary output.

06

Figma

Variables, component properties, documentation frames and QA playgrounds.

The token system turns editorial values into reusable roles for evidence, source credibility, disclosure, investigative visualization and accessible product surfaces.

Token reference

Every token, its role, and its value.

Primitive tokens
Token name	Role	Value
`--pds-yellow`	Brand accent	#ffd700
`--pds-black`	Base text	#000000
`--pds-white`	Base surface	#ffffff
`--pds-gray`	Secondary text	#666666
`--pds-danger`	Destructive action	#d4183d

Semantic tokens
Token name	Role	Value
`--cds-background`	Page surface	#ffffff
`--cds-background-inverse`	Dark surface	#161616
`--cds-layer-01`	Card surface	#ffffff
`--cds-layer-02`	Inset/gray surface	#f4f4f4
`--cds-layer-03`	Nested surface	#e0e0e0
`--cds-text-primary`	Primary text	#161616
`--cds-text-secondary`	Secondary/metadata	#525252
`--cds-text-on-color`	Text on dark/color	#ffffff
`--cds-border-subtle`	Dividers, card borders	#e0e0e0
`--cds-border-strong`	Input borders	#8d8d8d
`--cds-interactive`	Links, active states	#0f62fe
`--cds-support-error`	Error states	#da1e28
`--cds-support-warning`	Warning states	#f1c21b
`--cds-support-success`	Success states	#198038

Spacing tokens
Token	Value	Space	Typical use
`--space-01`	2px	02px	Micro gaps, hairlines
`--space-02`	4px	04px	Tight internal spacing
`--space-03`	8px	08px	Component internal padding
`--space-04`	12px	012px	Dense layout gaps
`--space-05`	16px	016px	Default padding
`--space-06`	24px	024px	Card padding
`--space-07`	32px	032px	Section internal gap
`--space-08`	40px	040px	Large gap
`--space-09`	48px	048px	Section padding top/bottom
`--space-10`	64px	064px	XL gap
`--space-11`	80px	080px	Page section padding

Typography tokens
Token	Stack	Role
`--type-display`	Akhand, Big Shoulders Display	Headlines, hero text
`--type-sans`	Anek Latin, Helvetica Neue	UI, body, product text
`--type-serif`	Noto Serif, Georgia	Citations, metadata, quotes
`--type-mono`	ui-monospace, SFMono	Token names, code, captions

Component library

Core product primitives meet editorial trust patterns.

These families are entry points. Each card links to a guide below, so the inventory does not stop at naming parts; it explains how the parts should behave.

InputsText input, textarea, checkbox, radio, switch, select, combobox, date picker and file upload.View guide ↓ NavigationHeader, shell, sidebar, breadcrumbs, tabs, pagination, menu and command palette.View guide ↓ FeedbackNotifications, toasts, alerts, dialogs, drawers, loading states, skeletons and progress.View guide ↓ Data displayData table, structured list, cards, tiles, badges, tags, metrics, charts and source cards.View guide ↓ EditorialArticle header, byline, author card, citation, footnote, pull quote, transparency and correction patterns.View guide ↓ Assisted reviewResearch request, reviewed response, approval request, confidence indicator, source drawer and memory disclosure.View guide ↓ VisualizationBar, line, area, scatter, heatmap, timeline, network, relationship map and geospatial styles.View guide ↓ TemplatesFront page, deep dive article, research report, dissent archive, research workspace and assisted workspace.View guide ↓

Component guide

Inputs

Inputs should feel calm and precise. The person using them may be entering sensitive source details, field notes or publication metadata, so the form has to be clear before it is clever.

Text input

Field report transcript

✓ Consent on file

Source type ▾

Use forSource metadata, research filters, upload flows, consent notes and publication settings.

BehaviorLabels stay visible, errors explain the fix, required fields are explicit and keyboard paths are complete.

IncludeDefault, focus, filled, error, disabled, loading and privacy-sensitive states.

Component guide

Navigation

Navigation should help people keep their place across long reports, archives and workspaces. It should not ask them to remember where evidence lives.

OverviewSourcesEvidenceTimeline

Use forGlobal headers, section jumps, article progress, archive browsing and workspace switching.

BehaviorCurrent location is visible, labels stay short and deep sections remain reachable from keyboard and touch.

IncludeDesktop, mobile, collapsed, active, overflow and long-title states.

Component guide

Feedback

Feedback should say what happened, what changed and what to do next. It should avoid drama, especially around errors and sensitive material.

Info: Source metadata saved.

Warning: Two claims need citation review.

Error: Private data cannot be exported.

Use forSave states, review warnings, upload progress, publication blockers and offline recovery.

BehaviorMessages are specific, non-color cues are present and destructive actions require a deliberate step.

IncludeInfo, success, warning, error, loading, empty and undo states.

Component guide

Data display

Data display components should make evidence easier to compare. They need strong scanning behavior without hiding source context.

IDEvidence itemStatus

01Transcript segmentVerified

02Public announcementCited

Use forEvidence tables, source cards, metrics, archive rows, comparison lists and chart summaries.

BehaviorRows support sorting, filtering, selection, citation access and responsive reading.

IncludeDense, comfortable, empty, loading, selected, flagged and source-linked states.

Component guide

Editorial

Editorial components carry trust. They show who made the work, where claims come from and what has changed since publication.

Interview — Human rights lawyer, Lagos Correspondent A · March 12, 2024

VerifiedCited

Claims stay close to their sources.

Use forArticle headers, bylines, citations, footnotes, source notes, pull quotes and correction blocks.

BehaviorProvenance remains close to the claim, and metadata supports reading instead of interrupting it.

IncludeAuthor, contributor, source, citation, update, correction and transparency states.

Component guide

Assisted review

Assisted review components can help a team move through research, but they should never sound like an unquestioned authority. They need source links, confidence cues and human approval.

Reviewed summary: Three cited signals found; one claim remains unresolved.

Needs reviewSources attached

Use forResearch requests, reviewed summaries, source drawers, confidence notes and approval checkpoints.

BehaviorClaims link back to evidence, uncertain material is marked and private context is clearly disclosed.

IncludeDraft, cited, uncertain, needs review, approved, rejected and memory/privacy states.

Component guide

Visualization

Visualizations should clarify relationships, time, geography and scale. Decoration is secondary to accountability.

SelectedComparisonUncertain

Use forTimelines, maps, relationship networks, ranking charts, heatmaps and uncertainty views.

BehaviorCharts expose sources, avoid color-only meaning and include readable alternatives.

IncludeLegend, source, selected, low-data, no-data, uncertainty and mobile states.

Component guide

Templates

Templates turn the system into real work. They show how pages behave when content is long, evidence is dense and review is ongoing.

Global nav Article body Citations Related evidence

Use forFront pages, deep dives, research reports, archives, workspaces and settings pages.

BehaviorTemplates define regions, hierarchy, responsive behavior and required trust surfaces.

IncludeDesktop, tablet, mobile, empty, loading, archived and review-in-progress states.

Editorial system

Trust is a component category.

I am treating research foundations as a first-class layer in The Polis Project Design System. Citations, source quality, verification states and editorial transparency are not ornamental details.

Editorial trust patterns for The Polis Project
Pattern	Interface responsibility	Evidence behavior	Status cue
Source card	Show origin, date, author, excerpt and credibility notes.	Connect claims to inspectable sources.	Verified
Citation	Make provenance visible inside articles, assisted summaries and reports.	Expose metadata without disrupting reading.	Cited
Fact check	Flag weak support, missing context and unresolved claims.	Require human review before publication.	Needs review
Investigation flow	Represent collection, synthesis, verification and publication.	Preserve the path from raw material to final claim.	In progress

Assisted review and data systems

Machine help never stands in for evidence.

When machine assistance is part of the workflow, the interface should keep people in control: show sources, name uncertainty, protect private context and require human review before publication.

18

Assisted review

Research requests, reviewed responses, approval flows, source drawers, memory controls and feedback states.

Human review

19

Data visualization

Chart taxonomy, accessible encodings, uncertainty styling, geospatial maps, timelines, networks and source-linked insight cards.

Accessible charts

20

Patterns page

Research workflows, data exploration, collaboration, review, loading, empty, error and dashboard workspace patterns.

Governed workflow

Visual language

The full visual kit for a public-interest design system.

A complete system needs more than components. It needs color behavior, typography, spacing, iconography and editorial rules that can survive reports, workspaces, dashboards and public archives.

Color ramps

Polis Yellow is the activist signal. Neutral ramps carry the work. Risk ramps support harm, evidence gaps and destructive states.

#fff8cc#ffec66#ffd700#c7a800#7a6700#3d3300

#ffffff#f4f4f4#e0e0e0#8d8d8d#525252#161616

#ffd7d9#ff8389#da1e28#a2191f#750e13#2d0709

Foundation specimens

Foundations shown as usable visual decisions.

This section visualizes the foundations I need for The Polis Project: color, typography, spacing, iconography, motion, accessibility and editorial voice.

Typography scale

Production type roles separate display, headings, body and metadata.

displayReportageAkhand 800

headingEvidence archiveAkhand 800

bodyReadable research text for dense public-interest products.Anek 400

metadataSource, date, citation, confidence.Noto Serif 100

Spacing system

Spacing follows predictable increments for dense dashboards, longform articles, review panels and chart surfaces.

8 16 24 32 48

layout component editorial review chart

Iconography

The initial icon inventory favors research actions and trust states over generic decoration.

Search Find sources, evidence, or archive entries

Source Attach or view a primary source document

Verified Source has passed editorial review

Warning Claim requires additional verification

Map Geolocate an event, source, or field report

Assist AI-assisted synthesis or research support

Agent Automated research or monitoring agent

Memory Persistent context or archived session data

Timeline Place event on an investigation timeline

Network Show relationships between entities or sources

Archive Move to long-term storage, read-only

Review Mark for editorial or human approval

Motion

Product motion is fast and quiet. Editorial motion is slower but still utilitarian. Assisted review states must be inspectable and pause-safe.

110ms

Productive

Hover, focus, active, menu and disclosure transitions.

UI

240ms

Expressive

Section reveal, drawer entry and data exploration transitions.

Narrative

Accessibility

Non-color cues, visible focus, keyboard paths, table semantics, chart alternatives and machine-assistance labels are required.

AA minimum AAA contrast mode Reduced motion Data alt text

Voice and content

Copy should be direct, factual and accountable. It should not inflate certainty, hide evidence gaps or let machine assistance sound like final judgment.

Disclosure: This summary includes machine-assisted synthesis and requires human source review before publication.

Component states

Core components need visible states, not just names.

The component board shows representative states for buttons, fields, notifications, data tables, assisted review messages, editorial source cards, overlays and workflow approvals.

Buttons

Primary -> Secondary -> Ghost -> Destructive !

Form fields

Source titleDefault input state

Claim confidenceEvidence required before publishing

Notifications

Info: Source metadata has been attached.

Warning: Two claims need citation review.

Error: Private data cannot be exported.

Data table

IDEvidence itemStatus

01Transcript segmentVerified

02Public announcementCited

03Claim clusterReview

Assisted review thread

Researcher: Summarize verified signals only.

Assistant: I found three cited signals and one unresolved claim.

Citations required

Source card

Interview transcript

Author, location, date, consent status, excerpt and verification history appear together.

VerifiedPrimary sourceField note

Approval drawer

Human approval controls are explicit for machine-assisted outputs.

Approve with citations ✓ Request edits -> Block publish !

Loading and empty

Skeletons, inline loading and empty states must explain next action without implying the system knows more than it does.

Extended component specimens

Every component shown in its actual states.

Source card

Field interview Verified

Interview — Human rights lawyer, Lagos, March 2024

Correspondent A · March 12, 2024 · Consent on file

Three separate sources confirmed the detention order was signed by a regional official without judicial oversight.

Verified Primary source Confidential

Open source -> View in context ->

Citation specimens

The report connects the detention order to a broader pattern of administrative removals.^[1]

UN Special Rapporteur Report, 2023

Special Rapporteur · United Nations · 2023

View source →

Cited

Editorial components

Correspondent A Field correspondent · Lagos bureau Published March 12, 2024

The records had been sealed, but the pattern was already visible to anyone who knew where to look.
— Field report, March 2024

Correction — March 15, 2024

An earlier version of this article incorrectly stated the order was signed on March 8. The correct date is March 10.

~~Original: The order was signed on March 8.~~

Form controls

Checkbox

Unchecked ✓Checked —Indeterminate

Radio

Unselected Selected

Toggle

Off On

Select

Select source type ▾

Navigation patterns

Tabs

Overview

Sources

Evidence

Timeline

Breadcrumbs

Home / Research / Lagos Bureau / Interview transcripts

Modal / dialog

Rendered as a static illustration.

Archive this source? ✕

This source will be moved to the archive. Active citations will remain but the source will be marked as archived.

Archive Cancel

Skeleton states

Article

Source card

Table

Confidence indicator

A Polis-specific component for assisted review outputs.

High confidence90%

3 sources cited — all verified Verified

Moderate55%

1 source — additional verification needed Needs review

Low confidence20%

Unverified — do not publish Unverified

Confidence indicators must always link to the underlying source evidence. Never display a score without a path to inspect the sources.

Data visualization

Investigative graphics need uncertainty, provenance and access.

I am defining chart foundations for public-interest reporting: non-color encodings, source-visible insights, uncertainty styling, map patterns, timelines and relationship networks.

Signal ranking

Bar charts use yellow sparingly to highlight selected evidence, with neutral comparison values.

Selected signalComparison signal

Investigation timeline

Timeline marks pair visual sequence with dates, sources and confidence states.

Mar 04Source received

Mar 08Claim logged

Mar 12Verified

Mar 15Correction

Event markerReview duration

Relationship network

Network views are for explainable relationships, never decorative complexity.

Claim cluster Interview Court file Official order Timeline

Verified relationshipContext relationship

Templates

Page-level compositions make adoption real.

A complete design system includes templates that combine components into real product and editorial surfaces: front pages, research reports, workspaces, review tools, archives and admin settings.

Deep dive article

NavGlobal navigation — sticky

HeaderHeadline · Byline · Date · Topic tags

Hero imageFull-width photo or graphic

BodyArticle text — 680px reading column

CitationsSource cards + footnotes

RelatedEvidence links and related reports

HeaderByline and date are required trust surfaces

BodyMax 680px centered reading column

CitationsRight rail — sources stay close to claims

Research report

NavGlobal navigation

Report headerTitle · Authors · Date · Classification

SummaryExecutive summary

FindingsFinding 1 · Finding 2 · Evidence

SourcesSource panel

ConfidenceEvidence + score

FooterStatus · Version · Review date

Report headerYellow — high visibility trust surface

Findings (65%)Primary reading column

Source panel (35%)Evidence visible alongside findings

Research workspace

NavGlobal navigation

Source tree

Document

Review panel

Status barConnection · Sync · Review state

Source treeArchive navigation — always visible

DocumentPrimary work surface

Review panelDark — distinguishes AI context from content

Implementation

Design artifacts need code contracts.

I am pairing the visual system with React packages, Tailwind presets, CSS variables, Style Dictionary-compatible JSON, Storybook documentation and Figma Variables.

{
  "color": {
    "semantic": {
      "background": "{color.primitive.white}",
      "text.primary": "{color.primitive.black}",
      "accent.research": "{color.primitive.yellow.50}",
      "status.error": "{color.primitive.red.60}"
    }
  }
}

:root {
  --pds-background: #ffffff;
  --pds-text-primary: #000000;
  --pds-accent-research: #ffd700;
  --pds-layer-01: #f4f4f4;
}

export {
  Button,
  TextInput,
  SourceCard,
  Citation,
  ReviewMessage,
  ConfidenceIndicator,
  DataTable
} from "@polis/react";

stories/
  foundations/
  tokens/
  components/
  editorial/
  ai/
  visualization/
  templates/
  qa/

Build roadmap

I am organizing the system as a phased production plan.

The sequence moves from setup through research, foundations, tokens, components, editorial systems, assisted review, visualization, patterns, templates, assets, governance and final release materials.

00

Project setup and source of truth

Repository, Figma page architecture, decisions, dashboard, naming and design-to-code contract.

Foundation

01-02

Research and foundations

Competitive analysis, Polis differentiation thesis, principles, color, typography, layout, motion, interaction, accessibility and editorial voice.

Research

03-05

Tokens and core components

Primitive, semantic, component and theme tokens followed by product UI components and documentation shells.

System build

06-10

Editorial, review, data, patterns and templates

Domain systems for journalism, assisted-review governance, investigative visualization, workflows and page-level compositions.

Domain value

11-12

Assets, governance, QA and release

Icons, media guidelines, themes, documentation site, contribution templates, QA strategy and portfolio case-study materials.

Production

QA and governance

Every phase ends with an audit.

I am designing the system to be inspectable through decision logs, changelogs, token checks, component audits, accessibility hardening and release notes.

Accessibility floor

WCAG 2.1 AA is the minimum target, with AAA support for high-contrast mode when feasible. Data visualization, citations, machine-assistance disclosures and keyboard behavior are explicit audit areas.

WCAG AA Keyboard Contrast Screen reader

Governance model

Contribution templates require rationale, impact, token and component implications, accessibility implications and review requirements. Assisted-review safety is part of governance, not an afterthought.

Decision log Changelog Migration Deprecation

TokensPrimitive values map to semantic roles, themes override semantics, and components do not hard-code decisions.

ComponentsEvery component includes size, state, keyboard, error, loading and responsive behavior.

EditorialCitations, source cards, corrections, bylines and transparency patterns are inspected together.

Review safetyAssisted outputs disclose machine involvement, cite sources, show confidence and preserve human approval paths.

VisualizationCharts provide source labels, non-color encodings, uncertainty treatment and text alternatives.