atproto Thingiverse but good
polymodel DESIGN.md
13 kB · 207 lines


Design System: Polymodel #

1. Overview #

Creative North Star: "The Drafting Table"

Polymodel looks like a set of well-kept engineering blueprints rendered for the web. The page is drafting paper; content sits on crisp bordered panels with near-square corners; technical metadata is set in monospace the way a drawing carries its measurements; empty media reads as a faint drafting grid awaiting geometry. The teal primary is drawing-ink blue; a single warm orange is the one action accent, used like a redline. It is a product surface: design serves the task of browsing, judging, downloading, and publishing printable things. The tool should disappear into the work.

This system explicitly rejects the flat-SaaS dashboard look (rounded cards everywhere, purple/blue gradients, soft shadows, Inter-for-everything) and the reflexive dark-terminal "developer tool" aesthetic. Warmth comes from the paper tone, the humanist type, and the orange accent — not from decoration. Familiarity is a feature: a maker fluent in Printables should trust every control on sight.

Key Characteristics:

  • Drafting-paper base, drawing-ink teal, single warm-orange action accent.
  • Near-square corners (2px panels, 0px controls); crisp 1px borders over shadow.
  • Monospace for all technical metadata (dimensions, formats, DIDs/handles, counts, status).
  • Drafting-grid placeholders instead of gray boxes.
  • First-class light and dark schemes; restrained, state-driven color and motion.

2. Colors #

A restrained palette: a tinted drafting-paper neutral ramp, one drawing-ink teal that carries structure, and a single warm orange reserved for action. Every token has a dark-scheme value (see assets/styling/theme.css; tonal/dark values live in the .impeccable/design.json sidecar).

Primary #

  • Drawing-Ink Teal (#1f6d8a): The structural brand color — active tabs, selected state, focus rings, section emphasis, grid lines (at low alpha). Carries identity without being the action color.

Secondary #

  • Slate Teal (#5a8797): Supporting teal for secondary controls and quieter structural accents.
  • Deep Teal (#0f4159): High-emphasis teal for hover ink and strong labels against light surfaces.

Tertiary #

  • Redline Orange (#c5652a): The single warm action accent — primary buttons and the one element that should pull the eye to "do this." Action only, never decoration.
  • Rust Link (#a24d1f): Inline text links, distinct from the action button so links don't read as buttons.

Neutral #

  • Drafting Paper (#f5f1e8): The body background. A warm paper tone tinted toward the brand — the blueprint substrate, not a generic off-white.
  • Sheet (#fffdf7): Raised panel/card/surface background.
  • Blueprint Overlay (#e8edf0): Cool inset background for media wells and grid placeholders.
  • Ink (#17252f): Body text.
  • Emphasis (#0c1f2c) / Subtle (#445461) / Muted (#6a747b): The text-emphasis ramp; pick by importance, never drop body to muted-gray on the paper base.
  • Border (#a9b8bf): The 1px line on every panel, control, and pill.
  • Highlight (#d8e5e9): Selection/skeleton shimmer tint.

Status #

  • Error (#a13f32) / Warning (#b36a16) / Success (#2d7358): Semantic state only, paired with shape/label, never color-alone.

Named Rules #

The One Redline Rule. Redline Orange (#c5652a) is the action accent. It marks the single primary action in a view and nothing decorative. If two things on a screen are orange, one is wrong.

The Paper-Is-Identity Rule. The body background is drafting paper (#f5f1e8), a deliberate tinted neutral — not the AI warm-cream default. Never rename it --paper/--cream/--sand and never swap it for a flat #fff/off-white; the paper tone carries the blueprint metaphor.

The Ink-Not-Gray Rule. Body text reaches for the ink end of the ramp. Light-gray "for elegance" on the tinted paper is the contrast trap; when a value is close to 4.5:1, move toward Ink/Emphasis, not Muted.

3. Typography #

Heading Font: Proza Libre (with system-ui, -apple-system, Segoe UI, sans-serif) Body Font: Proza Libre (with system-ui, -apple-system, Segoe UI, sans-serif) Label/Mono Font: Ioskeley Mono (with IBM Plex Mono, Consolas, monospace)

Character: One humanist sans (Proza Libre) carries headings, body, labels, and buttons — warm and legible, the workshop-manual voice. A distinctive monospace (Ioskeley Mono) carries everything technical, like dimensions stamped on a drawing. The contrast axis is sans-vs-mono, not two near-identical sans faces.

Hierarchy #

  • Heading (Proza Libre, 600, ~1rem–1.18rem, line-height 1.3): Card titles, section and page headings. Fixed rem scale, tight ratio.
  • Body (Proza Libre, 400, 16px, line-height 1.55): Paragraphs and descriptions; cap prose at 65–75ch.
  • Title (card) (Proza Libre, 600, clamp(1rem, 1.8vw, 1.18rem)): The one tolerated small fluid step, for thing-card titles in a fluid grid.
  • Meta/Label (Ioskeley Mono, ~0.72rem, letter-spacing 0.04–0.08em, often uppercase): Dimensions, file formats, DIDs/handles, counts, status pills, eyebrows/kickers.

Named Rules #

The Mono-Is-Metadata Rule. Monospace is reserved for technical metadata (measurements, formats, identifiers, counts, status). Prose and UI labels are never mono; metadata is never set in the body sans.

The Fixed-Scale Rule. Product headings use a fixed rem scale, not fluid clamp() — a heading that shrinks inside a panel looks worse, not designed. The card-title clamp is the only sanctioned exception.

The One-Eyebrow Rule. The uppercase tracked mono kicker (.eyebrow/.product-kicker) is part of the voice for deliberate, occasional use — never an eyebrow stacked above every section.

4. Elevation #

Flat by default. Depth comes from crisp 1px borders and tonal layering (paper → sheet → overlay), not shadows. The only shadow in the system is a 1px hairline under panels that reads as a sheet of paper lifting off the table, not a floating SaaS card.

Shadow Vocabulary #

  • Paper hairline (box-shadow: 0 1px 0 color-mix(in srgb, var(--color-text) 8%, transparent)): The single resting elevation on cards/panels. Borders do the structural work; this only seats the sheet.

Overlay tokens #

  • Scheme-independent lighting overlays for the 3D viewer stage and SVG preview live as tokens (--overlay-highlight-soft, --overlay-highlight, --overlay-shadow). They are pure white/black at low alpha (highlight/shadow) and read correctly in both schemes; call sites use the token, never an inline rgb(...).

Named Rules #

The Border-Over-Shadow Rule. Structure is drawn with 1px borders and background-tone steps, never with soft drop shadows. Never pair a 1px border with a wide (≥16px) soft shadow on the same element (the ghost-card tell).

5. Components #

Buttons #

  • Shape: Near-square (2px radius); base controls render at 0px corners. Never round to pill (except deliberate tags) or 12px+.
  • Default: Sheet background, 1px border, ink text. Hover shifts border to teal and text to deep teal.
  • Primary: Redline Orange fill, paper-colored text — the one action. Hover brightens slightly (filter: brightness(1.04)), no transform bounce.
  • Secondary / Ghost: Teal border + deep-teal text (secondary); transparent background (ghost).

Chips / Tabs / Status pills #

  • Style: 1px border, near-square, mono text, ~0.72rem. Transparent at rest.
  • State: Active tab / selected pill take a teal border, deep-teal text, and an 8% teal wash. Muted and error variants recolor the border + text + faint wash to match the semantic role.
  • Pill radius: --radius-pill (999px) is reserved for genuinely round badges — the circular part-index marker and deliberate tag chips — never for cards, inputs, or buttons.

Cards / Containers #

  • Corner Style: 2px (panel radius).
  • Background: Sheet (#fffdf7) over the paper base.
  • Border: 1px Border (#a9b8bf) — the defining line.
  • Shadow Strategy: Paper hairline only (see Elevation).
  • Internal Padding: ~1rem; metadata rows in mono, subordinate to title/creator.
  • Media: Drafting-grid background (20px grid, grid-line color) for previews and placeholders — never a flat gray box; missing media draws nested registration rectangles, not fake content.

Inputs / Fields #

  • Style: Paper-base fill, 1px border, 2px radius, body sans.
  • Focus: Border shifts to teal with a 2px translucent teal outline (outline: 2px solid color-mix(... primary 25% ...)). Focus is always visible.
  • Error / Disabled: Error recolors border+text to Error and adds a faint wash; disabled drops contrast and removes the pointer affordance.
  • Product nav (wordmark, Browse, Search, Publish, session control), not demo/workflow copy. Standard top-bar pattern; active state uses the tab treatment. Reachable search globally.

Signature: the blueprint preview / skeleton #

The drafting-grid media well (.blueprint-media) and the shimmer skeletons (.skeleton-*, blueprint-skeleton keyframes) are the system's signature. Content loads through skeletons over a stable grid, never a centered spinner.

6. Do's and Don'ts #

Do: #

  • Do reuse the tokens in assets/styling/theme.css and the component vocabulary in base.css/cards.css; extend, don't fork.
  • Do set all technical metadata (dimensions, formats, DIDs/handles, counts, status) in Ioskeley Mono.
  • Do keep body/placeholder contrast ≥ 4.5:1 in both schemes; move text toward Ink, not Muted, when close.
  • Do ship every interactive state — default, hover, focus, active, disabled, loading, error — with visible keyboard focus.
  • Do use drafting-grid placeholders and skeletons for loading/empty media; write empty states that teach (publish-your-first-thing).
  • Do keep motion to 150–250ms, ease-out, for state/feedback/loading/viewer-readiness only, with a prefers-reduced-motion fallback.

Don't: #

  • Don't swap the drafting-paper base for a flat off-white, or rename it --paper/--cream/--sand.
  • Don't round cards/inputs to 12px+ or reach for full pills outside tags; the near-square corner is the identity.
  • Don't use more than one Redline-Orange action per view, or use the action color for decoration.
  • Don't use gradient text, glassmorphism-by-default, hero-metric templates, identical icon-card grids, or an uppercase eyebrow above every section.
  • Don't pair a 1px border with a wide soft drop shadow (ghost-card), use border-left >1px as a colored stripe, or animate <img> on hover.
  • Don't put a display font — or any non-mono face — in technical metadata, or drop body text to muted gray on the paper base.
  • Don't land on generic flat-SaaS or generic dark-terminal looks; the answer to "what is this" is the blueprint identity.