Spec — Design system

2026-refresh › design-system · feature · created 2026-08-05 · spec · plan.html

One visual language for everything the refresh renders — context cards, re-skinned slides, editing overlays, the on-screen recording look — chosen by Asim from rendered candidates (never from descriptions), then delivered as reusable templates and tokens that every sibling task consumes instead of inventing its own look.

Problem

P1Four different looks already exist, and none was ever chosen — drift is happening before production has even started.
The card v1 (dark slate/amber, liked at golden-sample review), the callback-hell pilot's warm theme (built unsanctioned), the scope-chain spike's look, and the 2018 originals' style all coexist. Two spikes produced two visually incompatible pages — Asim's own observation. Without one landed language, every rendered artefact adds a fifth look.
P2"We'll talk styling later" is blocking three sibling tasks — cards, slide re-skins and edited output all need the answer.
back-catalogue-ops can't batch ~35 cards, slides-reskin can't render a frame, and lecture-editing can't design overlays until the look exists. The style conversation was deliberately parked during the spikes; this task is where it happens.
P3The merged course spans a decade of footage and must read as one product — the rendered surfaces are the stitching.
2016 DevTools, 2018 slides/VS Code, 2019 facecam, 2026 recordings. The cards, re-skins and overlays are what a student sees knitting those eras together — if they're incoherent, the course looks patched rather than refreshed.
P4The old marks point at a world that no longer exists — @jawache and CodeCraft are retired; nothing replaces them yet.
The 2018 slides carry a Twitter-era handle; 2016 browser footage carries CodeCraft. Both are already decided out. What on-screen mark (if any) replaces them — and how it points at Asim's current world — is a design call that lands here.
candidate boardsAsim picks, rendered A/B tokenspalette · type · marks card template v2 slide/diagram kit overlay kit · profile look → back-catalogue-ops (~35 cards) → slides-reskin · event-loop re-records → lecture-editing · lecture-production
The task's shape: a decided look becomes tokens, tokens become the three template kits + the profile look, and sibling tasks consume them.

Solution at a glance

J0Asim picks the course's look from rendered candidates, and from then on no sibling task ever makes a style decision. The pick becomes design tokens (palette, type, spacing, marks) and four consumable artefacts: the card template v2, a slide/diagram kit for re-skins and re-records, an editing overlay kit, and the pinned recording-profile look.

Job stories

J1 · When we decide the look

J1.1I choose from rendered candidates, side by side — real frames of real course moments, never descriptions or mood words P1Four looks already existnone was chosen
The method that already worked for the upscale decision: candidate boards showing the same card, the same slide moment and the same overlay in each direction (the existing card v1 and the pilot's warm theme enter as candidates, not incumbents; an asim.dev-terminal direction is a third). Judged at 1× on a real lecture context.
J1.2Nothing ships in a look I haven't signed off — sign-off is per surface, recorded, and spikes never count as approval P1Four looks already existtwo spikes drifted unsanctioned
The lesson of the pilot's unsanctioned restyle, made structural: each surface (card, slide, overlay, profile) carries an explicit Asim sign-off before any batch rendering starts.

J2 · When a sibling task needs the look

J2.1Cards come out of a template, not a design session — copy in, on-brand card out; ~35 without another style decision P2Styling blocks three taskscards are the biggest batch
v2 of the existing Remotion ContextCard, restyled to the chosen tokens; the card-copy file convention stays as-is.
J2.2Slides and diagrams come out of a kit — the re-skins and event-loop re-records build from parameterised Remotion pieces P2Styling blocks three tasksslides-reskin can't render a frame P3A decade of footage, one productre-skins are the stitching
Remotion is the decided vehicle for rendered graphics/animation (Asim: better than the old slide stack). The kit covers the recurring shapes: title/agenda slides, code-on-card, the event-loop diagram family, animated emphasis.
J2.3Editing reaches for a stocked overlay kit — emphasis boxes, arrows, lower-thirds, "UP NEXT" bumpers, in the same language P2Styling blocks three tasksoverlays are post-production's vocabulary
Pointing-at-things moved to post (decided during the spike conversations) — so the overlay kit is what replaces the live mouse-waving of the old recordings.
J2.4The recording profile wears the same language — theme, font and layout of the on-camera VS Code, pinned once P3A decade of footage, one productnew takes should look designed, not default
The ten-minute call deferred from lecture-production's spec lands here: the isolated recording profile inherits the system's editor theme/font so takes match the rendered surfaces.
J2.5Anything later starts from the tokens — advjs.asim.dev consumes the same palette/type/marks rather than re-deciding them P4Old marks are retiredthe replacement must be reusable
Tokens live as one small file/reference page; the landing task styles itself from them.

J3 · When a student watches across eras

J3.1Every rendered surface reads as one product — and the on-screen mark points at Asim's current world, consistently P3A decade of footage, one productcards/re-skins/overlays are the stitching P4Old marks are retired@jawache and CodeCraft are gone
The watermark/mark decision (what it says — likely the course's own home once advjs-landing exists — where it sits, how loud it is) is taken once, here, and applied by every kit. Untouched 2016/2019 footage keeps its era; only rendered/re-rendered surfaces carry the new language.

Constraints

Deferred to plan

Which candidate directions get boarded, and how many
Why it must wait: building boards is the task's first phase — the candidates (card v1's slate/amber · the pilot's warm theme · an asim.dev-terminal direction · anything Asim adds) are inputs to render, not spec decisions. The style itself is explicitly NOT decided in this spec.
What the on-screen mark says
Why it must wait: depends on advjs-landing's domain being real (the mark most plausibly points there) and the board review. Options as understood: advjs.asim.dev · asim.dev · no mark at all.

Decisions

Remotion renders all designed graphics — cards, slides, overlays
Asim: "using Remotion for graphics and animation is much better than some of the slide stuff I'd used in the past." Rejected: reviving the 2018 Keynote-style deck, hand-made one-offs.
@jawache and CodeCraft marks are retired everywhere we render
Decided during the format recon; both point at a world that no longer exists.
Existing looks enter as candidates, not incumbents
The liked-but-not-locked card v1 and the pilot's warm theme compete on the boards like everything else — "we're still doing spikes" (Asim). Nothing is grandfathered.
Emphasis lives in post-production overlays, not live mouse-pointing
Asim's call during the automation conversations; makes takes cleaner and emphasis repeatable.

Estimated files / edits

Size: M