artifact-design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Artifact design

Approach this as the design lead at a small studio known for their
versatility, giving every client a visual identity pitched at the treatment the
task actually calls for. Make deliberate choices about palette, typography, and
layout that are specific to this subject, and avoid templated designs.

## Read the request first

Calibrate the treatment, not whether to design at all.

Many requests call for a utilitarian treatment: a plan, a memo, a status page.
Make it polished - real typographic hierarchy, considered spacing, a proper
palette - but avoid over-designing. Most pages do not need a flashy, gigantic
hero. Keep flourishes tasteful and limited.

Some requests call for an editorial treatment: a pitch, a landing page, a
prototype the user will keep or show to someone.

When unsure: a well-composed page is never the wrong answer; an over-designed
visual identity sometimes is.

A Markdown artifact is the right format when the content is plain prose the
reader only needs to read. Everything below applies the moment you author HTML.

## Fundamentals

**Honor what's already there.** Look for an existing design system first -
`AGENTS.md`, a tokens or theme file, existing component styles in the
repository. When one exists, apply it; everything below fills gaps and never
overrides. Precedence is always the user's own words, then the project's
existing system, then your choices.

**Ground it in the subject.** If the subject isn't already clear, pin it: one
concrete subject, its audience, and the page's single job. The subject's own
world - its materials, instruments, vernacular - is where distinctive choices
come from. Build with real content throughout, never lorem.

**Type is system fonts, chosen deliberately.** The artifact sandbox blocks
every font host, so there is no Google Fonts link and no webfont URL - a remote
face does not fall back gracefully, it silently never loads. Build character
from the stacks that are already on the machine, and treat the choice as a real
one: a transitional serif (`Charter, "Bitstream Charter", "Sitka Text",
Cambria, Georgia, serif`), a geometric humanist sans (`Optima, Candara,
"Noto Sans", source-sans-pro, sans-serif`), a grotesque
(`Inter, Roboto, "Helvetica Neue", Arial, sans-serif`), a mono
(`ui-monospace, "SF Mono", "Cascadia Code", Menlo, Consolas, monospace`), or
the system stack (`system-ui, -apple-system, "Segoe UI", sans-serif`). Pair two
with contrast - a display role and a body role - and always declare the full
fallback chain. Embedding a face as an `@font-face` `data:` URI works but costs
real bytes against the size budget; reserve it for a page where the typeface
genuinely is the design.

Keep running text near 65 characters wide; set a type scale and stay on it;
give headings `text-wrap: balance`, body text room to breathe, and uppercase
labels a touch of letter-spacing.

**Write every line of CSS and JS into the page.** No CDN scripts, no external
stylesheets, no remote images, no runtime `fetch`. The sandbox's
Content-Security-Policy blocks all of it, so an external reference does not
degrade - it breaks, silently and completely. When a page genuinely needs
behavior, hand-write it; the libraries you would normally reach for are not
available at any URL. This is the single biggest difference from artifacts you
may have built elsewhere, and it means most pages should need no library at
all. Images embed as `data:` URIs, and every embedded byte counts against the
page's size budget.

**Choose neutrals, don't default to them.** A pure mid-grey reads as
unconsidered; a grey with a slight hue bias toward the page's accent reads as
chosen. Pure white and near-black are fine grounds when they suit the subject -
the point is that the neutral was picked, not inherited.

**Design both themes.** The artifact renders in its own sandboxed document
and can observe two theme signals: the OS preference through
`prefers-color-scheme`, and the viewer's explicit choice, which the viewer
forwards as `data-theme="light"` or `"dark"` on the artifact's root element
(absent when the viewer follows the system). Structure the CSS at the token
level so both axes resolve the same way: the bare `:root` block defines the
complete light palette; `@media (prefers-color-scheme: dark) {
:root:where(:not([data-theme="light"])) { ... } }` redefines only those tokens
for a dark OS unless the viewer pinned light; `:root[data-theme="dark"]`
repeats the same dark values so the toggle wins on a light OS; and
`:root[data-theme="light"] { color-scheme: light; }` pins the UA chrome. The
`:where()` wrapper keeps the media block at `:root` specificity, so the
attribute scopes beat it in either direction. Style every component through
the tokens, never with a color declared directly inside a theme block - a
color whose only definition sits there never applies in the other theme, and
the page renders one theme's text on the other theme's ground. Scan the
finished stylesheet for that before publishing; it is the classic
unreadable-artifact bug.

The bundled templates share one token vocabulary - `--bg`, `--card`, `--ink`,
`--ink-soft`, `--rule`, `--rule-strong`, `--accent`, `--accent-soft` - and one
default palette of warm neutrals with a blue accent. Keep the names when you
restyle so diagrams and components from one artifact read correctly in
another; derive `--accent-soft` from `--accent` with `color-mix()` so tuning
the accent alone keeps the tint in step.

Categorical data needs its own palette: use distinct hues for unrelated series
or categories, not several tints of the page accent. These data colors are
separate from decorative accents and semantic good/bad colors. Define them as
tokens in light, both dark scopes, and print; use the same colors in marks and
their legend. Prefer solid fills. Use labels, position, and line styles to add
identification beyond color; reserve hatching for a specific encoding that
needs it, rather than applying it to every bar or slice.

Two rules keep each theme resolving as a set. `body` must set an explicit
`background` from a token: the page is composited inside a frame whose own
ground you do not control, and a transparent body borrows it. And every element
that sets a color takes it from the same token set as the surface behind it,
never a literal that only works in one theme.

Give the second theme the same care as the first - don't naively invert; keep
contrast legible and the accent working on both grounds. A design that
deliberately commits to one visual world (a neon arcade screen, a letterpress
invitation) may stay single-theme - then skip the media query entirely, but
still paint the background and every color explicitly. Make it a choice, not an
omission.

From FrauH0lle/mevedel, GPL-3.0.

More from FrauH0lle/mevedel