DESIGN.md

FeatureLens design system

FeatureLens is a research instrument. Its interface should help someone operate an experiment and read evidence; it is not a landing page, growth dashboard, or software-company product surface.

Visual direction

The visual reference is a compact scientific workbench: editorial headings, neutral controls, dense but readable tables, restrained plots, and very little decorative chrome. The interface should feel designed by someone who expects to inspect numbers for a while.

Typography

• Display / section headings: Georgia, Cambria, Times New Roman, serif fallback.
• Body, controls, table cells: Segoe UI, Helvetica Neue, Arial, sans-serif fallback.
• Monospace is reserved for token chips and literal identifiers where fixed-width text helps scanning.
• Hierarchy comes from scale, weight, and spacing—not from badges, italics, all-caps kickers, or a different treatment for every subsection.
• Long explanatory prose should stay near 70–80 characters per line even though the analytical canvas is wide.

Color roles

• Accent: muted teal #6F8984.
• Secondary series: umber #8A735D, red-grey #8C6A67, plum #786F82, stone #82827E, blue-grey #687982.
• Neutrals come from Gradio's grey theme tokens so light and dark appearance remain usable.
• Saturated default categorical chart colors should be avoided when a fixed series set is known.
• No gradients, neon accents, glows, glass effects, or decorative beige/cream surfaces.

Geometry and surfaces

• Radius: approximately 2 px. Controls may be slightly rounded but should never look pill-shaped.
• No nested-card hierarchy. Groups exist for layout/state only and are visually flat.
• Avoid drop shadows. The only shadow permitted is the temporary in-place focus mode for dense tables/plots.
• Use rules, alignment, and whitespace instead of containers-within-containers.
• Do not add left-border "accent cards" or side-tab callouts.

Spacing

• Spacing is intentionally uneven by semantic role: related controls are tight; a new experiment has more separation.
• Section headings should sit close to the controls/results they introduce.
• Table titles use the otherwise-empty table toolbar band rather than consuming another row of vertical space.
• Do not introduce uniform 16/24/32 px spacing everywhere simply because it is convenient.

Components

Header

One title and one factual subtitle. Do not show version badges, status chips, marketing claims, or repository trivia in the live header.

Tabs

Flat text navigation with one active underline. No tab pills or raised nav cards.

Buttons

• Primary experiment action: compact muted-teal button.
• Utility action (Copy TSV, candidate hand-off): quiet secondary button.
• Button text should describe the action (Rank candidates, Run intervention) rather than generic calls to action (Continue, Get started).
• Do not make every button full-width on desktop.

Forms

Labels are literal and stable because validation instructions refer to them. Helper text is only included when the field's semantics are not obvious from the label.

Tables

Tables are primary research objects, not decorative cards. Use explicit headings, normal-weight data, tabular numerals, bounded height, horizontal scrolling for genuinely wide schemas, and a quiet Copy TSV utility.

Plots

Plots use a small, restrained palette and preserve their aspect ratio in focus mode. A plot should not expand to fill every available screen dimension. Export filenames should describe the figure rather than defaulting to chart.png.

Results copy

Measured values first. Caveats should be local and short; long methodological qualification belongs in Method or the offline report. Avoid paragraphs that restate what the immediately adjacent table already shows.

Information architecture

• Guide — how the evidence ladder works.
• Workbench — inspect one residual location and intervene on one feature.
• Feature sets — joint-feature interventions and geometry.
• Features — discovery, triage, controlled comparison, target profiles, and feature diagnostics.
• Paraphrases — robustness to rewording.
• Layers — early/middle/late SAE trajectory.
• Study — artifact-backed offline results only.
• Method — formulas, control discipline, and interpretation boundaries.

The global context line is the single source of truth for the current Workbench prompt/layer/token. Do not repeat separate context cards in each tab.

Anti-patterns

Do not add any of the following without a specific functional reason:

• card grids for simple prose;
• cards nested inside cards;
• status-chip or badge collections;
• gradients, glassmorphism, glow, or oversized decorative backgrounds;
• AI/SaaS language such as "unlock", "supercharge", "powerful", or "all-in-one";
• eyebrow/kicker labels above ordinary headings;
• tiny numbered or Roman-numeral section labels;
• every section centered or symmetrically weighted;
• the same font for headings, prose, code, and tabular data;
• full-width primary buttons by default;
• explanatory text that narrates a bug fix or implementation history;
• visible release/version marketing in the public application.

Review checklist

Before changing the public UI, check:

1. Does the change improve operating or reading the research tool?
2. Is it using an existing type, color, spacing, and button role?
3. Can a border/card/help paragraph be removed without losing meaning?
4. Does the result remain readable in dark and light appearance?
5. Did we preserve exact field/button terminology used by validation docs?
6. Did we avoid spending ZeroGPU quota merely to test an unchanged inference path?