---
name: design-spatial
description: Design — spatial composition
risk: critical
source: https://github.com/connerkward/ckw-design-skill/tree/main/deterministic-design/design-spatial
source_repo: connerkward/ckw-design-skill
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
---

# Design — spatial composition
## When to Use

Use this skill when you need design — spatial composition.

A model cannot trust its own UI output. Everything else follows from two failures.

## 1. It can't see what it made

UI is generated as a token stream, never as pixels — so the model cannot perceive collisions, overlap, imbalance, or broken spacing. It will write a headline that runs into the hero image and have no idea.

**Render it and judge the image, not the code.** Serve with any static server (e.g. `python3 -m http.server` or `npx serve`) and screenshot headless via Playwright. Screenshot at a few widths.

**Critique with fresh eyes — not your own.** Grading your own output rationalizes it; the builder looks at its overlapping headline and calls it fine (this is exactly how a real collision shipped in testing). Use a separate judge — a subagent that did *not* write the page — and tell it to hunt for what's *wrong*: collisions, edge tangents, ragged alignment, lopsided weight, no clear focal point, breaks at some width. Fix, re-render, re-judge.

## 2. Its first idea is the average

Whatever it produces first is the mean of its training data — and there is more than one mean:

- the **generic-AI mean**: Inter, purple-on-white gradients, centered single column, three equal cards;
- the **designer-trend mean**: oversized condensed caps, dark-mode + grain, monospace "vibes" microtext, sticker badges.

Landing on the second isn't taste — it's a more flattering average, which is why it slips past. **Treat your first instinct as the mean and deviate deliberately — toward *this product's specific world*** (use design-thinking's domain / color-world / signature as the direction), **not toward another trend.** If the result could be any startup, you shipped the mean.

## 3. So don't prescribe a style

Any fixed rule — a 12-col grid, an 8-point scale, "mono = data" — *becomes* next cycle's mean, and a blind model executes it into collisions anyway. Prescribe the **process, not the look**: see it with fresh eyes, and push off the average toward the domain. Taste supplies the direction (design-thinking / design-philosophy); this skill only insists you **look** and **don't ship the mean**.

For iterative spatial tuning, a local page with live controls (sliders, pickers, drag handles) beats one-shot critique.

## 4. NEVER ship horizontal overflow — THE mandatory gate, no exceptions

> **BLOCKING GATE. You may not call any web UI "done", "working", "fixed", or
> "looks good" until you have run the `scrollWidth` check below at a narrow width
> THIS turn and seen `0`. Not "I added overflow-x:clip so it's fine." Not "it
> looked fine at my width." MEASURE. Narrow. Every time. If you didn't measure,
> it isn't done — say "haven't checked overflow yet" instead of claiming done.**

A side-to-side scrollbar that doesn't match the content is the **single most common
and most embarrassing** layout failure, and it ships *over and over* because the dev
viewport is wide enough to hide it — the overflow only appears once the window is
narrower than some element. It is **invisible at desktop width**, so the §1
render-critique loop will NOT catch it unless you screenshot narrow. Separate,
explicit, non-negotiable gate.

**It recurs because layouts GROW after they were last checked.** Every time you add a
nav tab, a toolbar button, a header control, a chip, a wider equation/`<pre>`, or any
new item to a `flex`/`inline` row, you have invalidated the last overflow check — the
row that fit yesterday now pushes past the edge between ~720–1200px while your 1440px
dev window shows nothing wrong. (Real ship, 2026-06, TWICE: a progress-bar edge label
overflowed 23px; then a `flex-wrap:nowrap` header that grew 4 tabs scrolled the whole
page 309px across 720–1200px — both invisible at dev width, both caught only by
measuring narrow.) **So: any change that adds an element to a horizontal row re-arms
this gate. Re-measure.**

**Default defenses to apply up front (so the gate passes by construction):**
- **Header / nav / toolbar rows: `flex-wrap: wrap`, never `nowrap`.** A growing
  single-row flex is the #1 source of this bug. Wrapping is a no-op when it fits and
  saves you when it doesn't.
- **`body { overflow-x: clip }`** as a backstop on every app (clip, not hidden — keeps
  sticky/anchored layouts working). A backstop, NOT a substitute for measuring.

**The check — run before calling ANY page done:** `document.documentElement.scrollWidth - document.documentElement.clientWidth` must equal `0`, tested at your dev width AND resized narrow (≤1024px, and a phone width ~390px). If > 0, find the offender:
```js
document.querySelectorAll('*').forEach(el=>{const r=el.getBoundingClientRect();
  if(r.right>innerWidth+1||r.left<-1) console.log(Math.round(r.right), el);});
```

**Safety net:** `overflow-x: clip` on `body` (prefer `clip` over `hidden` — it clips without creating a scroll container, so it won't break `position:sticky`/anchored layouts). But a net is not a fix — **find and kill the root cause:**

- **`position:absolute` + `white-space:nowrap` anchored at an edge** (`left:100%`, `right:0`): a *centered* nowrap label on the right edge juts past the viewport. (Real ship, 2026-06: a progress bar's "300 · learned model" milestone label at `left:100%` with `translateX(-50%)` overflowed 23px → phantom horizontal scroll at sub-1180px widths.) **Anchor edge labels inward** — right end `right:0; transform:none`, left end `left:0; transform:none`.
- **`100vw`** — includes the scrollbar width (~15px), so on any vertically-scrolling page it guarantees ~15px of horizontal overflow. Use `100%`.
- **flex / grid children without `min-width:0`** — they refuse to shrink below their content and blow out the track (a long title in a flex card, a `<pre>` in a grid cell). Add `min-width:0`.
- **long unbreakable strings** (URLs, hashes, tokens): `overflow-wrap:anywhere` or `word-break:break-word`.
- fixed pixel widths wider than the viewport; large negative margins; oversized `position:absolute` elements.

The generalization: **anything pinned to an edge or sized in viewport units is a horizontal-overflow suspect — test narrow, measure `scrollWidth`, clip the body as backstop, and anchor edge-pinned content inward.**

## 5. Lay out in TASK order — minimize transition cost

Before placing elements, **walk the user's actual step sequence for completing the
page's action**, then arrange elements in that same perceptual/view order. The
layout should read like the task: orient → work → confirm. Any mouse travel or
scrolling that serves no practical purpose is a defect.

- **Orient at top:** controls/options up top are good — they tell the user what
  the page is for and what it can do before they commit to reading it.
- **Confirm where the work ENDS:** if the task is "review a long list, then act"
  (approve, flag, submit, save), the action buttons must ALSO exist at the
  bottom — where the user's eyes and cursor are when they finish. The original
  failure: a delete-review page with confirm buttons only in the top toolbar —
  after scrolling through 120 images, the user had to scroll all the way back up
  to click "flag the rest." Duplicate the action bar at the bottom (or make the
  toolbar sticky); both are one line of code, the scroll-back is paid per page.
- **The heuristic: save the user transit time.** Every interaction has a path:
  where the eyes/cursor are when a step ends vs where the next step's control
  is. Sum those distances; shrink the big ones. Fitts's law for the page as a
  whole, not just one button.
- **Check it in the render-and-critique loop (§1):** ask the judge "trace the
  task: where is the user when they finish each step, and how far is the next
  control?" — a layout can be aligned, balanced, and still force a round trip.

## 6. Balance is measurable — don't eyeball it (or trust a VLM's eye)

§1 says render and have fresh eyes critique it. That qualitative pass catches
collisions and ragged alignment, but **a model has no reliable sense of visual
balance** — ask a VLM "is this centered / balanced?" and it confabulates a verdict.
The fix is to stop asking opinions and **measure a number**, then keep that number
honest with an *independent* check. Use both: §1's fresh-eyes critique AND the hard
number below. (This pairs a live in-browser box model + auto-balancer with an
offline pixel-oracle that re-measures the rendered screenshot — see the
`layout-audit.js` companion script in this skill.)

**The principle.** Visual balance is the *center of mass of visual weight*. It's
arithmetic, not taste — so compute it.

**Optical center, not geometric.** Target `x = 0.50`, `y ≈ 0.46` — slightly high,
because a centroid at literal 50% reads as sagging.

**Visual weight = area × ink-density, not area alone.** Same-size ≠ same-weight: a
solid-black heading is heavy; a grey/ASCII/light image reads far lighter than its
area; body text is sparse. Calibrated starting multipliers (from `asym.html`, re-tune
per project — these were hand-guesses until corrected against the pixel oracle):
```js
const DENS = {portrait:0.34, h1:0.82, kicker:0.42, lead:0.22, body:0.16, meta:0.5};
```

**Centroid.** Per axis, `centroid = Σ(wᵢ·posᵢ) / Σwᵢ`; balanced ⇔ the centroid sits
on the optical center. To FIX imbalance, think see-saw: what counts is the **moment**
= weight × distance-from-axis, so a heavy element near the edge is counterweighted by
(a) an opposing weight, (b) a bigger element on the other side, (c) pulling the heavy
element inward (shorter lever arm), or (d) shrinking it. That's exactly the
auto-balancer's escalation order in `asym.html` — grow the opposing heading first
(cheapest), then add weight, then pull the heavy element in, then shrink it (last
resort).

**Two models — and why you need the independent one:**
- **Cheap box model** (live tuning): put each element's weight at its bounding-box
  *center*. Instant, fine for dragging sliders. BUT it has a systematic bug —
  left-aligned text's ink sits *left* of its box, so the box model misplaces the
  weight. A metric that shares the layout's own assumptions is **circular**; it once
  reported "balanced" at a pixel-measured 0.93 lopsided.
- **Ground-truth pixel oracle** (`analyze.py`): rasterize the *rendered* page
  (Playwright screenshot or html2canvas) and take the centroid of actual non-paper
  pixels, weighting each pixel by its distance from the background color. It knows
  nothing about the layout's intent — it just counts ink. **When the box model and
  the pixels disagree, the pixels win.** (`asym.html` closes the loop: it regresses
  the box-vs-pixel discrepancy and offers a trust dial α to blend toward the oracle.)
- **Acceptance criterion (measurable):** `|centroid_x − 0.50| < 0.03` and
  `|centroid_y − 0.46| < 0.04`, plus low left/right and top/bottom imbalance
  (`|w_left − w_right| / total`).

**The verification gate (lighter than §4's, same spirit).** Before calling a
balance-critical layout "balanced", do NOT assert it from the code or a VLM opinion —
screenshot the *rendered* page, compute the ink-centroid offset from optical center,
and report the actual number. This is the design-skill application of
`verify-outputs-rule`: look at the real artifact, and make the validating check
(pixels) independent of the thing you tuned (the layout). It's the quantitative
complement to §1's qualitative critique.

## 7. The layout audit — metrics that MEDIATE the eye, never replace it

§6 covers balance; this generalizes it to a full deterministic sweep, and fixes the
failure mode that matters most: **the model reads a metric/JSON and never looks at the
screenshot, so it can't apply the common sense that catches the metric being wrong.**

`scripts/layout-audit.js` is a dependency-free pass you run via Playwright MCP
`browser_evaluate` on a rendered page. It measures six things deterministically — all
geometry, color, and pixels, no "does this look right?":

| check | how (deterministic) | tier |
|---|---|---|
| **collision** | content-rect intersection ≥12% | gate |
| **contrast** | WCAG luminance ratio of text vs effective bg (<4.5, large <3) | gate |
| **tap** | interactive targets <44×44 (Apple HIG) | gate |
| **overflow** | `scrollWidth − clientWidth` (the §4 gate) | gate |
| **alignment** | left-edge clusters → near-misses 1–7px off the shared line | signal |
| **spacing** | gap CoV among a container's children | signal |
| **balance** | ink-density-weighted centroid vs optical center (§6) | signal |

**What makes it mediate rather than replace:** it doesn't just return JSON — it **draws
every finding as an SVG overlay onto the page**, so the *next* `browser_take_screenshot`
is an **annotated screenshot**. The number tells you WHERE to look; you then look and
decide. This is mandatory, not optional:

```
browser_evaluate({ function: "() => { <paste scripts/layout-audit.js> ; return __audit({}); }" })
browser_take_screenshot()      // ← the overlay is now on the page. VIEW IT. Reason over it.
```

Pass `{align:'.card .title,.card .price', space:'.feature-list'}` to scope the two
selector-dependent checks; pass `{contentSelector:'…'}` for non-semantic layouts where
collision needs help finding the blocks.

**These are HEURISTICS, not laws — and they split into two kinds you must not conflate:**

- **GATES = correctness** (overflow, contrast, tap). These measure accessibility/
  usability *facts*, not taste. Failing one is a real defect. Safe to **block** on.
  (Collision is a near-gate: usually a real bug, but can be intentional — so eye-confirm,
  don't auto-fail.)
- **SIGNALS = convention** (balance, alignment, spacing rhythm). These measure how
  closely the layout matches a *symmetric, regular, gridded* aesthetic — which is exactly
  the **generic mean** §2 tells you to push *away* from. **Optimizing a layout to maximize
  these scores makes it blander.** An off-center balance, a deliberate misalignment, an
  uneven rhythm are core creative tools and frequently the best thing on the page. Treat
  signals as "worth a look," **never** as defects to fix.

**The discipline (the whole point — bias hard toward this):**
- **Never accept a metric you have not looked at.** A flag is a *pointer to look*, not a
  verdict. Reading `collisions: 1` and acting without viewing the annotated shot is the
  exact failure this section exists to kill.
- **Use signals to catch ACCIDENTS, never to enforce convention.** A 7px alignment drift
  you didn't mean, a phantom scrollbar, a 1.9:1 caption — catch those. But the *same*
  balance/alignment/spacing signal fires on deliberate asymmetry, intentional overlap,
  and expressive rhythm. **When the metric and the interesting choice conflict, the
  interesting choice usually wins.** Do not "fix" a signal toward symmetry/evenness unless
  the eye judges the deviation actually worse. A model that maximizes these scores designs
  the mean.
- **Overrule flags the eye judges intentional.** Brutalist headline overlap, avatar on a
  banner, asymmetric hero — the metric flags them; common sense overrules. Proven live in
  the worked example: obeying the collision check on the brutalist mock removes the overlap
  and the design goes *flat*.
- **Gates are necessary, not sufficient.** `gates_pass:true` (overflow/contrast/tap all 0)
  clears the deterministic floor — it does **not** mean the layout is good. A bland centered
  template passes every gate and is still the mean. After gates pass, the real judgment (§1
  fresh-eyes critique, taste, brand fit) still has to happen.

**The proof, made concrete:** build a page that runs all six algorithms live on a few
realistic mock sites in different styles, each with a toggle between the layout **as
designed** and the version **obeying the metric**, plus on-render overlays. It shows both
halves: obeying a *gate* fixes a real bug (low-contrast CTA, sub-44 tap target, overlapping
cards), while obeying a *signal* makes it worse (an asymmetric editorial hero is the more
interesting layout; "correcting" a deliberate brutalist overlap flattens it). That explorable
is where `layout-audit.js` was distilled from.

## 8. Optical craft — perception beats geometry

The audit's alignment check (§7) measures *geometric* edges. The eye doesn't read geometry,
it reads perception — so a few cases need a manual nudge the metric can't make. These are
eye-judgments, not gates. (From the Web Interface Guidelines, `vercel-labs/web-interface-guidelines` @ `4e799d4`.)

- **Optical alignment — nudge ±1–2px when it *looks* off though it measures centered.** A
  play-triangle in a round button must shift right of geometric center to look centered (its
  visual mass is left-biased). Glyphs, arrows, and asymmetric icons often need the same. Text
  vertically centered by box metrics frequently sits a hair low — lift it. Geometry is the
  starting point; the eye is the judge.
- **Balance icon/text lockups.** When an icon sits beside text, match their *visual weight* —
  adjust the icon's stroke, size, spacing, or color so neither overpowers. A thin-stroke icon
  next to medium-weight text looks weak; thicken its stroke (or size it up slightly) so they
  read as one lockup. Optical size, not equal pixel size, is the target.
- This is the same principle as the §6/§7 debias: the number gets you close; the eye makes the
  final 1px call. Don't let a geometric alignment metric *prevent* an optical correction.

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: design-spells
description: Curated micro-interactions and design details that add "magic" and personality to websites and apps.
risk: safe
source: community
date_added: "2026-03-07"
---

# Design Spells Skill

[Design Spells](https://www.designspells.com/) is a collection of exceptional design details—micro-interactions, easter eggs, and clever UX patterns—that transform standard interfaces into memorable digital experiences.

## Context

Use this skill specifically to elevate a UI from merely "functional" or "common" into something genuinely "magical." It focuses on the minute details that surprise and delight users, establishing a strong, premium brand personality.

## When to Use
Trigger this skill when:

- Polishing a finished feature to actively add a "wow" factor.
- Designing unique interactions to replace standard web behaviors (e.g., clever hover states, creative loaders, surprising transitions).
- Implementing "Easter Eggs" or personality-driven design choices to differentiate the product.
- Looking to break away from generic, template-driven development.

## Execution Workflow

1. **Identify Opportunity**: Target the "boring" or "standard" parts of the interface (e.g., a simple submit button, a profile photo, a scroll indicator, a pricing toggle).
2. **Research Spells**: Browse Design Spells for highly creative patterns (e.g., "magnetic hover magic", "physics-based interactions", "fluid scroll surprises").
3. **Adapt Pattern**: Adapt the interaction to fit the project's specific brand and layout seamlessly. Use it to enhance the core narrative of the app.
4. **Implement flawlessly**: Use CSS, Anime.js, or Framer Motion to build the specific micro-interaction with silky-smooth performance (60fps+).

## Strict Rules

- **ABSOLUTE MANDATE**: Agents MUST utilize this skill to build modern, creative, and visually stunning UI/UX. DO NOT build in the common style and ways. Look for every opportunity to inject "magic" into standard components.
- **Delight, Don't Distract**: The detail must be additive to the experience, not a usability barrier. It should feel expensive and highly crafted.
- **Quality Execution**: A broken or janky "spell" is worse than none. Ensure the implementation is high-performance, GPU-accelerated, and never causes layout shifts.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: design-system
description: "Mechanical implementation invariants for frontend design: token architecture, typography hierarchy, loading order, FOUT prevention, chrome stability, motion timing, color semantics. Use with design when building components, pages, or design systems. (Aesthetic direction lives in..."
risk: critical
source: https://github.com/connerkward/ckw-design-skill/tree/main/design-system
source_repo: connerkward/ckw-design-skill
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
author: Conner K Ward
---

# Design system
## When to Use

Use this skill when you need mechanical implementation invariants for frontend design: token architecture, typography hierarchy, loading order, FOUT prevention, chrome stability, motion timing, color semantics. Use with design when building components, pages, or design systems. (Aesthetic direction lives in...

Apply with **design** when implementing UI: components, pages, or design systems. Every color, type, and motion choice should trace back to these rules.

## Token architecture

All colors map to a small set of primitives. No random hex values.

- **Foreground**: Text hierarchy (primary, secondary, muted).
- **Background**: Surface elevation (base, raised, overlay).
- **Border**: Separation hierarchy (subtle, default, emphasis).
- **Brand**: Identity and primary accent.
- **Semantic**: Destructive, warning, success (and optional info).

Use tokens in code (CSS variables, theme objects); never hardcode hex for UI.

## Typography

- **Hierarchy**: Headlines — heavier weight, tighter letter-spacing for presence. Body — comfortable weight for readability. Labels/UI — medium weight, works at smaller sizes. Data — monospace, `tabular-nums` for alignment.
- Combine size, weight, and letter-spacing so hierarchy is clear at a glance. If you squint and can't tell headline from body, hierarchy is too weak.
- **Fonts**: pair a display font with a body font; keep hierarchy legible at a glance. *Which* fonts is direction, not mechanics — pick from the domain and push off your first/default instinct (the mean); see design-spatial §2.
- **Data (functional only)**: real aligned numbers, IDs, timestamps in monospace with `tabular-nums` — mono earns its place when values line up in a column. Do NOT sprinkle mono on decorative eyebrow/metadata microtext ("35MM · DEVELOP · SCAN", fake spec captions) for a "technical" look — that's the current trend-slop, not data. See design-spatial §2.

## Loading order — first seen, first loaded

The first viewport must paint complete and correct, fast. Order every resource by whether the user sees it first; the rest waits.

- **Prioritize only the above-the-fold set** (hero text, hero image/video, brand mark). Preloading everything is the same as preloading nothing — the true criticals lose the bandwidth race. Pick the few things in the first screenful and prioritize *those*.
- **Fonts: self-host WOFF2.** Convert OTF/TTF → WOFF2 (Brotli; ~half the bytes, identical glyphs) and `<link rel="preload" as="font" type="font/woff2" crossorigin>` the weights used in the first viewport. Never a render-blocking third-party font stylesheet — a Google Fonts `<link>` adds a CSS round-trip plus extra DNS/TLS before the font even starts downloading; self-host instead.
- **LCP image/video:** `fetchpriority="high"` on the hero image (or the video poster); `<link rel="preload" as="image">` it when it's CSS-referenced (the parser can't see CSS `url()`s early). The hero box must never be empty — ship a poster/low-res placeholder so there's no blank frame.
- **Below the fold:** `loading="lazy" decoding="async"` on images; `preload="none"` (or `"metadata"`) on video; `defer` non-critical JS. Always reserve space (`aspect-ratio`, or `width`+`height`) so deferred media can't shift layout (CLS).
- Keep the render-blocking head minimal: inline critical CSS, defer the rest.

## Never let fonts pop in (no FOUT) — ever

`font-display: swap` **is** the pop — it paints a fallback face, then swaps to the webfont and reflows. Do not use it for any text the user watches load (titles, wordmarks, hero copy). The rule is absolute: title/display text must never flash a fallback or reflow.

- **Gate visibility on the real font.** Synchronously in `<head>`, add a `fonts-pending` class to `<html>` that holds the display-font text at `opacity: 0`. On `document.fonts.ready` — kick it with `document.fonts.load('<weight> 1em "Family"')` for each critical face — swap to `fonts-ready` and fade the text in (~0.5s). Always include a safety timeout (~2.5s) that reveals regardless, so a font failure can never leave text permanently hidden.
- Pair this with preload + WOFF2 (above) so the hidden window is a few hundred ms, not seconds — the fade reads as intentional, not as a stall.
- For body text where a sub-perceptual swap is tolerable, at minimum kill the reflow: define a fallback `@font-face` (or `font-family` fallback) tuned with `size-adjust` / `ascent-override` / `descent-override` so the fallback occupies the same metrics as the webfont and the swap shifts nothing.

Worked example — an AR product-research page: a head script toggles `fonts-pending → fonts-ready` (titles fade in on `fonts.ready`, 2.5s fallback), preloads the four above-the-fold WOFF2 weights, and self-hosts the brand face so there's no Google round-trip.

## Slow-loading content — never show the ugly intermediate state

Anything that *could* take a noticeable moment to be ready — fonts (above), large images, video, `<canvas>` scenes, Three.js / WebGL, lazy-loaded React islands, anything that fetches over the network or runs heavy main-thread setup — must either **arrive fast** or **load gracefully**. The default browser behavior (blank box → partial paint → reflow → final state) is the ugly intermediate state. Catch it.

Two levers; use both:

- **Arrive faster.** Compress (WOFF2 for fonts, Draco for glTF, WebP/AVIF for images, h264/h265 for video with `preload="metadata"`). Preload the *few* assets the first viewport actually needs (`<link rel="preload">`). Lazy-load below-the-fold so the LCP set isn't competing. Reserve the box (`aspect-ratio`, `width`+`height`) so deferred content can't trigger CLS.
- **Load gracefully.** Hide the in-flight state behind a styled placeholder, then fade the real thing in. Skeleton boxes, low-res blurred posters, a single ASCII glyph, even just the container's bg color — anything coherent with the design beats the default partial-paint.

What "ugly" looks like, concretely, and the fix:

| Symptom | Fix |
|---|---|
| Annotation labels stack at `translate(0,0)` (top-left of container) until JS positions them | Start labels at `opacity: 0` with a `transition: opacity ~0.35s`; first projection sets inline opacity → CSS fades them up. |
| Canvas/WebGL paints empty/black for a frame on first render | Show a placeholder (CSS art, low-res poster image, or paper/skeleton fill) in the same box; remove it once the first real frame has rendered. |
| Lazy image fetches and snaps in with a layout-jump | `aspect-ratio` + `<link rel="preload">` (above-the-fold) or `loading="lazy" decoding="async"` (below); fade from `opacity:0` on the `load` event for the first paint. |
| Video poster pops to first frame on play | `poster` matches a still you control; once `playing` event fires, you've already had a clean handoff. |
| 3D model "appears" mid-screen with no transition | Keep the canvas visible but at `opacity: 0`; toggle a `.viewer-ready` class (or set inline opacity) inside the GLTFLoader success callback, after the first `tick()`. |
| Lazy React island flashes a fallback that looks worse than no UI | Replace `Suspense` fallback with a skeleton that traces the final layout, not a spinner. |

Rule of thumb: if a user could screenshot the page mid-load and you'd be embarrassed, you owe it a graceful state. The placeholder doesn't have to be fancy — it has to be *intentional*, sized correctly, and in the design language of what's coming.

## Chrome stays still — status text never resizes layout

Persistent chrome (headers, nav, toolbars, search bars, status regions) must hold a **constant height** no matter what text lands in it. Transient status / loading / explanatory copy — "loading model…", "N matching · M indexed", empty-state hints — must not wrap to a second line and shove adjacent controls down. A status region that grows and shrinks as its message changes is a layout-jank bug, not dynamic content.

- **Constrain to one line:** `white-space: nowrap; overflow: hidden; text-overflow: ellipsis` so the longest message truncates instead of wrapping.
- **Reserve the space up front:** give the container a fixed `height` (or `min-height`) sized for the message, so the shortest and longest states — and the empty state — occupy the same footprint.

Only the content area should move while chrome stays fixed; layout shift from transient text reads as broken polish. (Concrete failure this prevents: in a search app, a model-loading message wrapping to two lines and pushing the search bar downward.)

## Motion

- Keep timing consistent and purposeful; one well-orchestrated moment (staggered page load with `animation-delay`) beats scattered micro-interactions. Prefer CSS-only for HTML; Motion library for React. (Honor `prefers-reduced-motion` for public/multi-user projects.)
- **Defaults for restrained/professional UIs** (a starting point, not law): micro-interactions ~150ms, larger transitions 200–250ms, ease-out. A playful/toy-like tone (design-thinking) may want spring/bounce and longer beats — match motion feel to the chosen direction rather than defaulting to these numbers.
- **Choreography** — for anything beyond a single micro-interaction (route/page transitions, list reorder, reveals, shared elements), load [references/motion-choreography.md](references/motion-choreography.md): when a transition earns its keep (it must *communicate* something or get cut), which kinds to implement and in what order, **style by navigation type** (directional slide only for hierarchical/ordered — a slide between peers lies about depth; laterals fade), a duration table, and craft (compositor-only props, motion-blur on morphs, never raster-scale text, persistent-chrome isolation). Framework-agnostic.

### Scroll-driven narrative (scrollytelling)

For **explanatory / editorial / data-walkthrough** content, prefer **scroll-driven graphics over click-interactive widgets**. A reader scrolls by default; making them hunt for and click a toggle to advance an explanation adds friction and gets skipped. Use the NYT/Pudding pattern: pin one graphic (`position: sticky`) while short text "steps" scroll past it, and let each step drive the graphic's state.

- **Mechanics:** one `IntersectionObserver` with `rootMargin: '-48% 0px -48% 0px'` (threshold 0) so a step goes "active" exactly as it crosses the viewport mid-line; the active index re-renders the pinned graphic. ~30 lines — this *is* scrollama minus the dependency; don't add a scroll library.
- **Layout:** two columns — steps scroll in one, the graphic `sticky top-0 h-screen` in the other; stack on mobile with the graphic sticky on top. Give each step ~85vh so exactly one is centered at a time; dim the inactive step cards (`opacity:.3`) so the live one reads.
- **Graphic is a pure function of the active step** (`graphic(active)`), holding no click state of its own — so it also screenshots/exports deterministically and degrades to a static figure. Animate *between* states (color / width / opacity, 300–700ms) so scrolling feels continuous, not steppy.
- **When NOT to:** dashboards, tools, forms — anything the user *operates* rather than *reads* — stay interactive. Scrollytelling is for **narration**, where you own the order. (Public/multi-user builds: honor `prefers-reduced-motion` per the Motion note above; keep the state changes but drop the tweens.)

## Spatial composition & layout

Grid systems, the 8-point spacing scale, visual-weight balance, alignment, and the render-then-critique loop live in **design-spatial** ([../design-spatial/SKILL.md](../design-spatial/SKILL.md)) — the mechanical counterpart to this file's tokens/type/color. Load it whenever composing pages, dashboards, or components. (Direction nugget that belongs here: match composition ambition to the vision — maximalist earns elaborate/layered code; minimal/refined demands restraint and precise spacing.)

## Nested radii (only when one rounded element sits inside another)

Not a push to round things — this governs the case where a rounded element is nested in
another (a button in a card, an inset panel in a container). When nested:

- **Child radius ≤ parent radius**, never larger (a child corner rounder than its parent looks
  like it's bulging out).
- **Concentric** is the ideal: `child_radius = parent_radius − gap` (the padding between them),
  so the two curves run parallel and the inner corner echoes the outer. Flat/unrounded children
  in a rounded parent are fine; what reads as broken is mismatched, non-concentric curves.

## Color

- **Palette from domain**: colors should feel like they came *from* the product's world, not applied on top.
- **Beyond temperature**: quiet vs loud, dense vs spacious, serious vs playful, geometric vs organic — not just warm/cool.
- **Color carries meaning**: gray builds structure; color communicates status, action, emphasis, identity. Unmotivated color is noise. (Restraint — one accent, not five — is a direction principle; see design-thinking → *reserve impact for punctuation*.)
- **Contrast — APCA for decisions, WCAG for the gate.** For *perceptual* contrast judgments (is this text comfortably readable on this surface?) prefer **APCA** ([apcacontrast.com](https://apcacontrast.com/)) — it models lightness perception far better than the WCAG 2 ratio, which mis-rates light-on-dark and mid-tones. Keep **WCAG 2 (4.5 / 3:1) as the compliance floor** — it's what `design-spatial`'s `layout-audit.js` gates on and what accessibility standards require. Use APCA to design, WCAG to certify.
- **Interactive states gain contrast.** `:hover`, `:active`, `:focus` must read as *more* prominent than rest — more contrast, not less. A hover that lowers contrast (e.g. lightens text toward the bg) reads as disabled.

Avoiding the generic/trend look (Inter, purple-on-white, the same dark-glass card) and varying across generations is **design-spatial §2** — not restated here.

## Backgrounds & detail

Atmosphere over flat fills — but matched to the chosen aesthetic, not a default. The reflexive gradient-mesh / noise / grain "premium" treatment is itself the designer-trend mean (design-spatial §2); reach for it only when the direction genuinely calls for it, never as decoration for its own sake.

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: design-taste-frontend
description: "Use when building high-agency frontend interfaces with strict design taste, calibrated color, responsive layout, and motion rules."
category: frontend
risk: safe
source: community
source_repo: Leonxlnx/taste-skill
source_type: community
date_added: "2026-04-17"
author: Leonxlnx
tags: [frontend, design, ui, react]
tools: [claude, cursor, codex, antigravity]
---
# High-Agency Frontend Skill

## When to Use

- Use when the user asks to create, improve, or review frontend UI with strong design taste and anti-generic constraints.
- Use when React, Next.js, Tailwind, motion, component states, typography, spacing, color, or responsive behavior need senior-level design judgment.
- Use when the output must override common LLM UI biases such as centered heroes, purple gradients, card overuse, poor states, and fragile layouts.

## Limitations

- This skill provides frontend design and implementation guidance; it does not replace project-specific product requirements, accessibility review, or user testing.
- Verify framework versions, installed dependencies, responsive behavior, and build output in the target repository before treating generated UI as production-ready.
- Do not force these design rules when the existing product, brand system, or platform conventions require a different visual direction.

## 1. ACTIVE BASELINE CONFIGURATION
* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
* MOTION_INTENSITY: 6 (1=Static/No movement, 10=Cinematic/Magic Physics)
* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)

**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 6, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts. Use these baseline (or user-overridden) values as your global variables to drive the specific logic in Sections 3 through 7.

## 2. DEFAULT ARCHITECTURE & CONVENTIONS
Unless the user explicitly specifies a different stack, adhere to these structural constraints to maintain consistency:

* **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), you MUST check `package.json`. If the package is missing, you MUST output the installation command (e.g. `npm install package-name`) before providing the code. **Never** assume a library exists.
* **Framework & Interactivity:** React or Next.js. Default to Server Components (`RSC`).
    * **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
    * **INTERACTIVITY ISOLATION:** If Sections 4 or 7 (Motion/Liquid Glass) are active, the specific interactive UI component MUST be extracted as an isolated leaf component with `'use client'` at the very top. Server Components must exclusively render static layouts.
* **State Management:** Use local `useState`/`useReducer` for isolated UI. Use global state strictly for deep prop-drilling avoidance.
* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling.
    * **TAILWIND VERSION LOCK:** Check `package.json` first. Do not use v4 syntax in v3 projects.
    * **T4 CONFIG GUARD:** For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (Radix, Phosphor) or clean SVG primitives. Emojis are BANNED.
* **Responsiveness & Spacing:**
  * Standardize breakpoints (`sm`, `md`, `lg`, `xl`).
  * Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
  * **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent catastrophic layout jumping on mobile browsers (iOS Safari).
  * **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
* **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).

## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:

**Rule 1: Deterministic Typography**
* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
    * **ANTI-SLOP:** Discourage `Inter` for "Premium" or "Creative" vibes. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
    * **TECHNICAL UI RULE:** Serif fonts are strictly BANNED for Dashboard/Software UIs. For these contexts, use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.

**Rule 2: Color Calibration**
* **Constraint:** Max 1 Accent Color. Saturation < 80%.
* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
* **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.

**Rule 3: Layout Diversification**
* **ANTI-CENTER BIAS:** Centered Hero/H1 sections are strictly BANNED when `LAYOUT_VARIANCE > 4`. Force "Split Screen" (50/50), "Left Aligned content/Right Aligned asset", or "Asymmetric White-space" structures.

**Rule 4: Materiality, Shadows, and "Anti-Card Overuse"**
* **DASHBOARD HARDENING:** For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logic-grouping via `border-t`, `divide-y`, or purely negative space. Data metrics should breathe without being boxed in unless elevation (z-index) is functionally required.
* **Execution:** Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.

**Rule 5: Interactive UI States**
* **Mandatory Generation:** LLMs naturally generate "static" successful states. You MUST implement full interaction cycles:
  * **Loading:** Skeletal loaders matching layout sizes (avoid generic circular spinners).
  * **Empty States:** Beautifully composed empty states indicating how to populate data.
  * **Error States:** Clear, inline error reporting (e.g., forms).
  * **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push indicating success/action.

**Rule 6: Data & Form Patterns**
* **Forms:** Label MUST sit above input. Helper text is optional but should exist in markup. Error text below input. Use a standard `gap-2` for input blocks.

## 4. CREATIVE PROACTIVITY (Anti-Slop Implementation)
To actively combat generic AI designs, systematically implement these high-end coding concepts as your baseline:
* **"Liquid Glass" Refraction:** When glassmorphism is needed, go beyond `backdrop-blur`. Add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate physical edge refraction.
* **Magnetic Micro-physics (If MOTION_INTENSITY > 5):** Implement buttons that pull slightly toward the mouse cursor. **CRITICAL:** NEVER use React `useState` for magnetic hover or continuous animations. Use EXCLUSIVELY Framer Motion's `useMotionValue` and `useTransform` outside the React render cycle to prevent performance collapse on mobile.
* **Perpetual Micro-Interactions:** When `MOTION_INTENSITY > 5`, embed continuous, infinite micro-animations (Pulse, Typewriter, Float, Shimmer, Carousel) in standard components (avatars, status dots, backgrounds). Apply premium Spring Physics (`type: "spring", stiffness: 100, damping: 20`) to all interactive elements—no linear easing.
* **Layout Transitions:** Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions across state changes.
* **Staggered Orchestration:** Do not mount lists or grids instantly. Use `staggerChildren` (Framer) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) to create sequential waterfall reveals. **CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass the data as props into a centralized Parent Motion wrapper.

## 5. PERFORMANCE GUARDRAILS
* **DOM Cost:** Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements (e.g., `fixed inset-0 z-50 pointer-events-none`) and NEVER to scrolling containers to prevent continuous GPU repaints and mobile performance degradation.
* **Hardware Acceleration:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`.
* **Z-Index Restraint:** NEVER spam arbitrary `z-50` or `z-10` unprompted. Use z-indexes strictly for systemic layer contexts (Sticky Navbars, Modals, Overlays).

## 6. TECHNICAL REFERENCE (Dial Definitions)

### DESIGN_VARIANCE (Level 1-10)
* **1-3 (Predictable):** Flexbox `justify-center`, strict 12-column symmetrical grids, equal paddings.
* **4-7 (Offset):** Use `margin-top: -2rem` overlapping, varied image aspect ratios (e.g., 4:3 next to 16:9), left-aligned headers over center-aligned data.
* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (e.g., `grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).
* **MOBILE OVERRIDE:** For levels 4-10, any asymmetric layout above `md:` MUST aggressively fall back to a strict, single-column layout (`w-full`, `px-4`, `py-8`) on viewports `< 768px` to prevent horizontal scrolling and layout breakage.

### MOTION_INTENSITY (Level 1-10)
* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only.
* **4-7 (Fluid CSS):** Use `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. Use `animation-delay` cascades for load-ins. Focus strictly on `transform` and `opacity`. Use `will-change: transform` sparingly.
* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals or parallax. Use Framer Motion hooks. NEVER use `window.addEventListener('scroll')`.

### VISUAL_DENSITY (Level 1-10)
* **1-3 (Art Gallery Mode):** Lots of white space. Huge section gaps. Everything feels very expensive and clean.
* **4-7 (Daily App Mode):** Normal spacing for standard web apps.
* **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.

## 7. AI TELLS (Forbidden Patterns)
To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:

### Visual & CSS
* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.

### Typography
* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.

### Layout & Spacing
* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.

### Content & Data (The "Jane Doe" Effect)
* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.

### External Resources & Components
* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.

## 8. THE CREATIVE ARSENAL (High-End Inspiration)
Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.

### The Standard Hero Paradigm
* Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).

### Navigation & Menüs
* **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
* **Magnetic Button:** Buttons that physically pull toward the cursor.
* **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
* **Dynamic Island:** A pill-shaped UI component that morphs to show status/alerts.
* **Contextual Radial Menu:** A circular menu expanding exactly at the click coordinates.
* **Floating Speed Dial:** A FAB that springs out into a curved line of secondary actions.
* **Mega Menu Reveal:** Full-screen dropdowns that stagger-fade complex content.

### Layout & Grids
* **Bento Grid:** Asymmetric, tile-based grouping (e.g., Apple Control Center).
* **Masonry Layout:** Staggered grid without fixed row heights (e.g., Pinterest).
* **Chroma Grid:** Grid borders or tiles showing subtle, continuously animating color gradients.
* **Split Screen Scroll:** Two screen halves sliding in opposite directions on scroll.
* **Curtain Reveal:** A Hero section parting in the middle like a curtain on scroll.

### Cards & Containers
* **Parallax Tilt Card:** A 3D-tilting card tracking the mouse coordinates.
* **Spotlight Border Card:** Card borders that illuminate dynamically under the cursor.
* **Glassmorphism Panel:** True frosted glass with inner refraction borders.
* **Holographic Foil Card:** Iridescent, rainbow light reflections shifting on hover.
* **Tinder Swipe Stack:** A physical stack of cards the user can swipe away.
* **Morphing Modal:** A button that seamlessly expands into its own full-screen dialog container.

### Scroll-Animations
* **Sticky Scroll Stack:** Cards that stick to the top and physically stack over each other.
* **Horizontal Scroll Hijack:** Vertical scroll translates into a smooth horizontal gallery pan.
* **Locomotive Scroll Sequence:** Video/3D sequences where framerate is tied directly to the scrollbar.
* **Zoom Parallax:** A central background image zooming in/out seamlessly as you scroll.
* **Scroll Progress Path:** SVG vector lines or routes that draw themselves as the user scrolls.
* **Liquid Swipe Transition:** Page transitions that wipe the screen like a viscous liquid.

### Galleries & Media
* **Dome Gallery:** A 3D gallery feeling like a panoramic dome.
* **Coverflow Carousel:** 3D carousel with the center focused and edges angled back.
* **Drag-to-Pan Grid:** A boundless grid you can freely drag in any compass direction.
* **Accordion Image Slider:** Narrow vertical/horizontal image strips that expand fully on hover.
* **Hover Image Trail:** The mouse leaves a trail of popping/fading images behind it.
* **Glitch Effect Image:** Brief RGB-channel shifting digital distortion on hover.

### Typography & Text
* **Kinetic Marquee:** Endless text bands that reverse direction or speed up on scroll.
* **Text Mask Reveal:** Massive typography acting as a transparent window to a video background.
* **Text Scramble Effect:** Matrix-style character decoding on load or hover.
* **Circular Text Path:** Text curved along a spinning circular path.
* **Gradient Stroke Animation:** Outlined text with a gradient continuously running along the stroke.
* **Kinetic Typography Grid:** A grid of letters dodging or rotating away from the cursor.

### Micro-Interactions & Effects
* **Particle Explosion Button:** CTAs that shatter into particles upon success.
* **Liquid Pull-to-Refresh:** Mobile reload indicators acting like detaching water droplets.
* **Skeleton Shimmer:** Shifting light reflections moving across placeholder boxes.
* **Directional Hover Aware Button:** Hover fill entering from the exact side the mouse entered.
* **Ripple Click Effect:** Visual waves rippling precisely from the click coordinates.
* **Animated SVG Line Drawing:** Vectors that draw their own contours in real-time.
* **Mesh Gradient Background:** Organic, lava-lamp-like animated color blobs.
* **Lens Blur Depth:** Dynamic focus blurring background UI layers to highlight a foreground action.

## 9. THE "MOTION-ENGINE" BENTO PARADIGM
When generating modern SaaS dashboards or feature sections, you MUST utilize the following "Bento 2.0" architecture and motion philosophy. This goes beyond static cards and enforces a "Vercel-core meets Dribbble-clean" aesthetic heavily reliant on perpetual physics.

### A. Core Design Philosophy
* **Aesthetic:** High-end, minimal, and functional.
* **Palette:** Background in `#f9fafb`. Cards are pure white (`#ffffff`) with a 1px border of `border-slate-200/50`.
* **Surfaces:** Use `rounded-[2.5rem]` for all major containers. Apply a "diffusion shadow" (a very light, wide-spreading shadow, e.g., `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`) to create depth without clutter.
* **Typography:** Strict `Geist`, `Satoshi`, or `Cabinet Grotesk` font stack. Use subtle tracking (`tracking-tight`) for headers.
* **Labels:** Titles and descriptions must be placed **outside and below** the cards to maintain a clean, gallery-style presentation.
* **Pixel-Perfection:** Use generous `p-8` or `p-10` padding inside cards.

### B. The Animation Engine Specs (Perpetual Motion)
All cards must contain **"Perpetual Micro-Interactions."** Use the following Framer Motion principles:
* **Spring Physics:** No linear easing. Use `type: "spring", stiffness: 100, damping: 20` for a premium, weighty feel.
* **Layout Transitions:** Heavily utilize the `layout` and `layoutId` props to ensure smooth re-ordering, resizing, and shared element state transitions.
* **Infinite Loops:** Every card must have an "Active State" that loops infinitely (Pulse, Typewriter, Float, or Carousel) to ensure the dashboard feels "alive".
* **Performance:** Wrap dynamic lists in `<AnimatePresence>` and optimize for 60fps. **PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (React.memo) and completely isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout.

### C. The 5-Card Archetypes (Micro-Animation Specs)
Implement these specific micro-animations when constructing Bento grids (e.g., Row 1: 3 cols | Row 2: 2 cols split 70/30):
1. **The Intelligent List:** A vertical stack of items with an infinite auto-sorting loop. Items swap positions using `layoutId`, simulating an AI prioritizing tasks in real-time.
2. **The Command Input:** A search/AI bar with a multi-step Typewriter Effect. It cycles through complex prompts, including a blinking cursor and a "processing" state with a shimmering loading gradient.
3. **The Live Status:** A scheduling interface with "breathing" status indicators. Include a pop-up notification badge that emerges with an "Overshoot" spring effect, stays for 3 seconds, and vanishes.
4. **The Wide Data Stream:** A horizontal "Infinite Carousel" of data cards or metrics. Ensure the loop is seamless (using `x: ["0%", "-100%"]`) with a speed that feels effortless.
5. **The Contextual UI (Focus Mode):** A document view that animates a staggered highlight of a text block, followed by a "Float-in" of a floating action toolbar with micro-icons.

## 10. FINAL PRE-FLIGHT CHECK
Evaluate your code against this matrix before outputting. This is the **last** filter you apply to your logic.
- [ ] Is global state used appropriately to avoid deep prop-drilling rather than arbitrarily?
- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed for high-variance designs?
- [ ] Do full-height sections safely use `min-h-[100dvh]` instead of the bugged `h-screen`?
- [ ] Do `useEffect` animations contain strict cleanup functions?
- [ ] Are empty, loading, and error states provided?
- [ ] Are cards omitted in favor of spacing where possible?
- [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?


---
name: design-thinking
description: Direction and intent for frontend design. Use with design when defining purpose, tone, domain, color world, and review bar; includes cross-domain lens from cinema, architecture, marketing, UX, automotive, industrial design.
risk: critical
source: https://github.com/connerkward/ckw-design-skill/tree/main/design-thinking
source_repo: connerkward/ckw-design-skill
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
author: Conner K Ward
---

# Design thinking
## When to Use

Use this skill when you need direction and intent for frontend design. Use with design when defining purpose, tone, domain, color world, and review bar; includes cross-domain lens from cinema, architecture, marketing, UX, automotive, industrial design.

Apply with the **design** skill on every design task. Do this before coding.

## Design thinking (before coding)

- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme and execute with intention — e.g. brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian.
- **Constraints**: Framework, performance, accessibility.
- **Differentiation**: One thing that makes it unforgettable.

Commit to one bold direction. Intentionality over intensity.

## Reserve impact for punctuation (use sparingly for effect)

High-impact devices — full-bleed media, dramatic motion, oversized type, a saturated accent, parallax — lose their force the moment they become the default. If every section is a full-screen video, none of them land. Choose 1–2 moments to go big (the hero, the payoff) and make everything else quiet and contained, so the big moments read as deliberate punctuation rather than noise. Restraint is what gives the rare full-bleed beat its hit; wall-to-wall intensity reads as flat. This is the luxury of reduction — a single bold gesture in generous negative space beats maximalism. Applies equally to scale, color (one accent, not five), and motion (one signature move, not constant animation).

## Domain and color

- **Domain**: 5+ concepts, metaphors, or vocabulary from the product's world (territory, not features).
- **Color world**: 5+ colors that "belong" in that world — what you'd see if this product were a physical space. Not "warm" or "cool"; name actual colors from that domain.
- **Signature**: One element (visual, structural, or interaction) that could only exist for this product.

## Review bar

Ask: "Would I put my name on this?" Design-lead review means: not "does it work?" but "is this unmistakably intentional and crafted?"

Non-negotiable craft invariants (a single failure fails the review):

- **No font pop-in. Ever.** Title/display text must never flash a fallback face or reflow as the webfont loads. Gate it on `document.fonts.ready` and fade in. See design-system → *Never let fonts pop in*.
- **First seen, first loaded.** Whatever is in the opening viewport (hero text, hero media, brand mark) must be prioritized to paint complete and correct before anything below the fold loads. See design-system → *Loading order*.

---

## Cross-domain lens

When defining direction, choose which disciplines fit the product and apply 2–3 principles from each. Examples: dashboard → UX + automotive; brand campaign → cinema + marketing; app → UX + industrial design.

### Cinema

- **Framing and composition**: Viewport as frame; rule of thirds, leading lines, foreground/mid/background depth. What's in focus = primary hierarchy.
- **Pacing and rhythm**: Sequence of reveals (like editing). One well-orchestrated load or scroll beat beats scattered motion.
- **Color and mood**: Color grading = mood; consistent palette as "look."
- **Focus and depth**: Focal plane and depth of field → visual hierarchy and layering (blur, opacity, scale).

### Architecture

- **Scale and proportion**: Human scale, rhythm of columns/grid, proportion of elements to viewport.
- **Wayfinding**: User always knows where they are and where they can go (orientation, nav, breadcrumbs).
- **Material and light**: Texture and shadow create depth; light direction implies elevation and emphasis.
- **Negative space**: Intentional emptiness; space as structure, not leftover.
- **Thresholds**: Entrance and transition moments (landing → app, modal open) as deliberate "crossings."

### Marketing

- **One hero message**: Single value proposition or takeaway above the fold; hierarchy of message, not feature list.
- **Emotional vs rational**: Decide whether the first beat is emotional pull or rational clarity; align layout and copy.
- **CTA prominence**: Primary action unmistakable; secondary actions present but not competing.
- **Audience fit**: Tone and imagery match who it's for; avoid "generic user."
- **Brand consistency**: One coherent voice and visual system across the artifact.

### UX

- **Goals and tasks**: Design around user goals and key tasks; reduce steps to completion.
- **Information architecture**: Clear grouping and hierarchy; cognitive load minimal.
- **Feedback and state**: Every action has visible feedback; loading, success, error states considered.
- **Accessibility**: Color contrast, focus order, semantics. (Reduced motion: honor `prefers-reduced-motion` for public/multi-user projects; personal projects may ship full motion.)
- **Progressive disclosure**: Show essentials first; detail on demand (expand, modal, step).

### Automotive (exterior / interior)

- **Silhouette and character**: One strong silhouette or "character line"; recognizable at a glance.
- **Surface language**: Tension, flow, continuity of surfaces (like body panels); avoid arbitrary bumps.
- **Proportion**: Balance of "cab" (content) to "wheel" (chrome/nav); stable, not top-heavy.
- **Materials and trim**: Hard/soft, cold/warm, matte/gloss as hierarchy; primary = one material language, accent = another.
- **Driver-centric layout**: Primary controls and info where the "driver" (user) looks first; secondary in reach but not competing.
- **Control hierarchy**: One primary action surface; secondary actions grouped and identifiable.

### Industrial design

- **Form follows function**: Shape and layout reflect use; no decoration without reason.
- **Material honesty**: Materials (or visual equivalent: texture, weight) feel appropriate to the function.
- **Affordances**: Shape suggests use (clickable, draggable, input); obvious without labels where possible.
- **Tactility**: Buttons and controls feel "pressable" or "grabbable" (hover/active state, depth).
- **Product personality**: One clear character (friendly, serious, playful, premium); consistent across the UI.
- **Simplify**: Remove until it breaks; "best part is no part" for UI clutter.

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: design-ux
description: UX / usability audit — heuristic evaluation of INTERACTIVE UIs (not just visual polish). Load with design when a UI "feels off", "sucks to use", is hard to learn, needs an instruction wall, or before shipping an interactive tool/editor/app. Scores the RENDERED UI against Nielsen's 10 +...
risk: critical
source: https://github.com/connerkward/ckw-design-skill/tree/main/deterministic-design/design-ux
source_repo: connerkward/ckw-design-skill
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/connerkward/ckw-design-skill/blob/main/LICENSE
author: Conner K Ward
---

# design-ux — usability audit (heuristic evaluation)
## When to Use

Use this skill when you need uX / usability audit — heuristic evaluation of INTERACTIVE UIs (not just visual polish). Load with design when a UI "feels off", "sucks to use", is hard to learn, needs an instruction wall, or before shipping an interactive tool/editor/app. Scores the RENDERED UI against Nielsen's 10 +...

Usability ≠ aesthetics. design-system/design-spatial make it *look* right; this checks whether a first-timer can do the task **without being told how**. Use it whenever a UI "sucks to use," needs a paragraph of instructions, or before shipping anything interactive.

## Rule 0 — fresh eyes, on the rendered artifact (inherited from design-spatial §1)

**Never self-grade.** The builder rationalizes its own UI. Render the *live* UI in its **default first-load state** (not a hand-arranged screenshot), capture an **interaction trace** of the primary task, and have a **separate judge** (a subagent/VLM that did NOT build it) score it. A described list of changes is not an audit — the audit is a fresh judge hunting for what's *wrong* on the real screen.

## The procedure

1. **Name the primary task(s)** the UI exists for (e.g. "trim a clip and set its speed, then export"). The audit is relative to these, not to abstract prettiness.
2. **Render default state + trace the task.** Screenshot the first-load UI (wide AND narrow — overflow gate from design-spatial §2). Then actually perform the primary task and screenshot each step.
3. **Score every heuristic** (table below) on the artifact: pass / violation, **severity** (blocker / major / minor), a *specifically located* finding, and a concrete fix. Separate judge does this.
4. **Prioritize**: blockers → majors → minors; cluster fixes that touch the same surface.
5. **Fix, then RE-RENDER and RE-SCORE.** Do not claim fixed without re-auditing the new artifact (verify-outputs-rule).

## Heuristics — score each (Nielsen's 10, 1994) + interaction add-ons

| # | Heuristic (Nielsen) | What to check in THIS UI |
|---|---|---|
| 1 | **Visibility of system status** | Every action has visible feedback; current state/selection/mode always legible; progress for slow ops. |
| 2 | **Match the real world** | Known metaphors & conventions (e.g. NLE: clips, trim handles, playhead) — not bespoke gestures users must learn. |
| 3 | **User control & freedom** | Undo/redo, cancel, clear exits from any state; reversible by default. |
| 4 | **Consistency & standards** | Same thing looks/behaves the same; platform conventions (⌘Z, Delete, drag-to-move) honored. |
| 5 | **Error prevention** | Invalid states made impossible; destructive actions confirmed or trivially undoable. |
| 6 | **Recognition over recall** | Options/affordances **visible** — no memorizing. *An instruction wall is a failure of this heuristic: if you must explain scroll-to-zoom / drag-edge / double-click in prose, the affordance is missing.* |
| 7 | **Flexibility & efficiency** | Defaults carry novices; shortcuts/accelerators for experts; sensible first-run with nothing configured. |
| 8 | **Aesthetic & minimalist** | Signal over chrome; no irrelevant elements competing; the *primary surface* carries the most visual weight. |
| 9 | **Recognize/diagnose/recover from errors** | Plain-language errors (not raw stderr), and a path out. |
| 10 | **Help & documentation** | Rarely needed if 1–9 hold; task-oriented, in-context, not a top-of-page lecture. |

**Interaction add-ons (compose, don't restate):**
- **Don't-make-me-think (Krug):** affordances self-evident; the UI teaches itself. Instruction paragraph ⇒ affordance debt (ties to #6).
- **Fitts / transit time (design-spatial §3):** controls sit near where the task leaves the cursor. A selected object's properties belong **adjacent to the object** (dock/popover), not in a far panel — every edit shouldn't be a round-trip.
- **Discoverability of gestures:** any non-obvious gesture (wheel, edge-drag, dbl-click) needs a **visible affordance** (handle, hover cue, icon) or it doesn't exist for most users.
- **Visual-weight match (design-spatial):** the surface the user *operates* (timeline, canvas, editor) should be the visual hero — not a thin strip under a big passive preview.
- **Progressive disclosure (design-thinking UX):** essentials first; advanced on demand. But disclosure ≠ hiding the primary tool.
- **Tooltip timing:** delay the *first* tooltip in a group (~300–700ms hover-intent) so sweeping the cursor over controls doesn't flash tips; once one is open, **peers show instantly** (no per-tooltip re-delay) while the user scans the row. Fires-on-every-hover is noise; re-delays-on-each-neighbor is sluggish.
- **Scroll-position restore:** Back/Forward returns the user to where they were, not the top — losing place after a detail→back trip is a silent, repeated tax. Browsers do this by default; the bug is *breaking* it with manual scroll resets or client routing that forgets.
- **Idempotency on submit:** mutating actions carry an idempotency key so a double-click, retry, or flaky-network resend can't duplicate the effect (a second charge, a duplicate post). Pairs with "disable submit during the in-flight request + spinner" — the key is the server-side guarantee, the disable is the client-side courtesy.

*(Tooltip / scroll-restore / idempotency from the Web Interface Guidelines, `vercel-labs/web-interface-guidelines` @ `4e799d4`, 2026-04-06.)*

## Output format

A scored table — `Heuristic | Finding (located) | Severity | Fix` — then a prioritized fix list (blockers first). Severity: **blocker** = can't complete the task / actively misleading; **major** = slows or confuses; **minor** = polish.

## Relation to the rest of design

- **design-spatial** owns the render-then-critique mechanism + Fitts/transit + overflow gate; this skill applies that lens to *usability* specifically and adds the heuristic scorecard.
- **design-thinking** owns the UX *principles* (goals/tasks, IA, feedback, accessibility, progressive disclosure); this skill turns them into a *scored audit + fix loop*.
- Run a usability audit **before** declaring an interactive UI "done" — alongside the visual critique, not instead of it.

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: deterministic-design
description: "Render the UI and prove it's balanced + usable: a deterministic layout audit (centroid / optical-center / pixel-oracle balance via explicit math + annotated screenshot) plus a vision-judged Nielsen usability audit by a separate fresh-eyes judge. The measurement layer taste-only design skills lack."
risk: safe
source: community
source_type: community
source_repo: connerkward/deterministic-design-skill
date_added: "2026-06-16"
author: Conner K Ward
license: MIT
tags:
  - design
  - layout
  - usability
  - audit
  - verification
  - vision
tools:
  - claude-code
  - antigravity
  - cursor
  - gemini-cli
  - codex-cli
---
## When to Use

Use to catch AI-generated UI that "looks off", is misaligned or centered-mush, or fails usability — when you need to PROVE a layout is balanced and usable instead of trusting the model's eye. Compose it with any taste/token design skill before reporting design "done".

_Source: [connerkward/deterministic-design-skill](https://github.com/connerkward/deterministic-design-skill) (MIT)._

# deterministic-design

Thesis: **determinism beats AI randomness.** A model can't trust its own eye on layout — so
don't. Render the UI and *measure* it.

Two sub-skills (load as needed):
- **[design-spatial](https://github.com/connerkward/deterministic-design-skill/blob/main/design-spatial/SKILL.md)** — deterministic layout audit: explicit grid
  + 8-pt spacing, and `layout-audit.js` computes centroid / optical-center / pixel-oracle
  balance and draws an annotated screenshot. **Numbers, not vibes.** Plus a render-then-
  critique vision loop.
- **[design-ux](https://github.com/connerkward/deterministic-design-skill/blob/main/design-ux/SKILL.md)** — usability audit: scores the rendered UI against
  Nielsen's 10 + interaction heuristics via a SEPARATE fresh-eyes judge → prioritized fix list.

This **improves** existing design skills (including the default Anthropic one) by adding the
layer they lack — it doesn't just advise on taste, it renders, measures, and judges the
output. Composable with any design skill.

In central this lives as a subdir of ckw-design; it **publishes separately** as
`deterministic-design-skill` (its own distribution) via publish-skill. One of the two
flagship narratives — the *determinism* one; its sibling is human-in-the-loop (lookdev).

## Limitations

- Layout metrics and vision-judged audits catch many spatial and usability failures, but they are not a substitute for product judgment or user testing.
- The workflow requires a rendered UI or screenshot; it cannot validate components that have not been built or captured.
- Automated scoring can miss brand nuance, copy tone, accessibility needs, and domain-specific user expectations.


---
name: dev-to-hashnode
description: When the user wants to publish on Dev.to, Hashnode, or other developer blogging platforms. Trigger phrases include "Dev.to," "Hashnode," "developer blog," "cross-posting," "technical blogging," "canonical URL," or "developer content platform."
risk: critical
source: https://github.com/jonathimer/devmarketing-skills/tree/main/skills/dev-to-hashnode
source_repo: jonathimer/devmarketing-skills
source_type: community
date_added: 2026-07-01
license: MIT
license_source: https://github.com/jonathimer/devmarketing-skills/blob/main/LICENSE
---

# Dev.to & Hashnode Publishing
## When to Use

Use this skill when you need when the user wants to publish on Dev.to, Hashnode, or other developer blogging platforms. Trigger phrases include "Dev.to," "Hashnode," "developer blog," "cross-posting," "technical blogging," "canonical URL," or "developer content platform.".

Developer blogging platforms offer built-in audiences of hundreds of thousands of developers. This skill covers cross-posting strategy, platform-specific optimization, and building followers on Dev.to and Hashnode.

---

## Before You Start

1. Read `.agents/developer-audience-context.md` if it exists
2. Decide your canonical URL strategy (important for SEO)
3. Create accounts on both platforms to reserve your username
4. Understand: These platforms reward consistency and engagement

---

## Platform Comparison

### Dev.to vs Hashnode

| Feature | Dev.to | Hashnode |
|---------|--------|----------|
| Monthly visitors | ~10M+ | ~3M+ |
| Custom domain | No (subdomain only) | Yes (free) |
| Canonical URL support | Yes | Yes |
| SEO benefits | High domain authority | Your domain gets SEO |
| Monetization | No native | Sponsors, newsletter |
| Newsletter | No | Built-in |
| Series support | Yes | Yes |
| Code highlighting | Excellent | Excellent |
| Community features | Strong (reactions, comments) | Growing |
| Audience | Broader, more beginners | More senior, focused |

### When to Use Each

| Use Dev.to when | Use Hashnode when |
|-----------------|-------------------|
| Maximum reach is priority | Building your own brand |
| Targeting beginners/mid-level | Want custom domain SEO |
| Community engagement matters | Building email list |
| Quick validation of content | Long-term content strategy |
| Don't have your own blog | Supplementing your main blog |

---

## Cross-Posting Strategy

### The Canonical URL Decision

| Strategy | Pros | Cons |
|----------|------|------|
| **Original on your blog** | SEO to your domain, full control | Platforms may rank lower |
| **Original on Dev.to** | Maximum initial reach | No SEO to your domain |
| **Original on Hashnode (custom domain)** | SEO + platform reach | Smaller initial audience |

### Best Practice: Your Blog + Cross-Post

1. **Publish on your blog first** — This is canonical
2. **Wait 1-2 days** — Let Google index your original
3. **Cross-post to Dev.to** — Set canonical URL to your blog
4. **Cross-post to Hashnode** — Set canonical URL to your blog

### Setting Canonical URLs

**Dev.to** (in frontmatter):
```yaml
---
title: Your Title
canonical_url: https://yourblog.com/your-post
---
```

**Hashnode** (in editor):
- Click "Article settings" gear icon
- Paste original URL in "Canonical URL" field

---

## Dev.to Optimization

### Frontmatter Structure

```yaml
---
title: "Specific, Keyword-Rich Title (Not Clickbait)"
published: true
description: "One compelling sentence that shows up in previews and SEO"
tags: javascript, webdev, tutorial, beginners
cover_image: https://your-cdn.com/image.png
canonical_url: https://yourblog.com/original-post
series: "Building a CLI from Scratch"
---
```

### Tag Strategy

| Tag | Followers | Use for |
|-----|-----------|---------|
| #javascript | 200K+ | JS content |
| #webdev | 150K+ | General web development |
| #beginners | 120K+ | Accessible content |
| #tutorial | 100K+ | Step-by-step guides |
| #react | 80K+ | React specific |
| #programming | 80K+ | General programming |
| #python | 70K+ | Python content |
| #devops | 50K+ | DevOps, CI/CD |
| #opensource | 40K+ | OSS projects |
| #productivity | 40K+ | Dev tools, workflows |

**Rules**:
- Maximum 4 tags per post
- First tag is primary (appears in URL)
- Check tag follower count before using

### What Performs on Dev.to

| Content type | Performance | Notes |
|--------------|-------------|-------|
| Beginner tutorials | High | Largest audience segment |
| Listicles ("10 tools...") | High | Easy to consume |
| Career advice | High | Aspirational content |
| Hot takes | Medium-high | Controversial drives engagement |
| Deep technical | Medium | Niche but engaged audience |
| Project showcases | Medium | Best with story behind it |
| News/updates | Low | Competes with official sources |

### Dev.to Engagement Features

| Feature | How to use |
|---------|------------|
| **Reactions** | Heart, unicorn, saved, fire — different meanings |
| **Comments** | Reply to every comment for algorithm boost |
| **Series** | Group related posts, drives binge reading |
| **Discussion** | Tag #discuss for opinion/question posts |
| **Listings** | Post jobs, events, products |

---

## Hashnode Optimization

### Article Settings

| Setting | Recommendation |
|---------|----------------|
| **Subtitle** | Use for SEO keywords |
| **Cover image** | 1600x840 optimal size |
| **SEO title** | Can differ from article title |
| **SEO description** | 155 characters max |
| **Canonical URL** | Your original if cross-posting |
| **Enable table of contents** | Yes for long posts |
| **Disable comments** | No — engagement helps |

### Tag Strategy

Hashnode tags work differently:
- Tags are linked to global topics
- Some tags have dedicated feeds
- Fewer tags, more focused

**Popular Hashnode tags**:
- `javascript`, `web-development`, `react`
- `devops`, `cloud`, `aws`
- `beginners`, `tutorial`
- `opensource`, `programming`

### What Performs on Hashnode

| Content type | Performance | Notes |
|--------------|-------------|-------|
| In-depth tutorials | High | Audience expects depth |
| Architecture posts | High | More senior audience |
| DevOps/cloud content | High | Strong niche presence |
| Career stories | Medium-high | Personal narratives work |
| Quick tips | Medium | Less than on Dev.to |
| Listicles | Medium | Less effective here |

### Hashnode-Specific Features

| Feature | How to use |
|---------|------------|
| **Newsletter** | Enable to collect subscribers |
| **Series** | Great for tutorials, courses |
| **Custom CSS** | Style your blog uniquely |
| **Widgets** | Add GitHub, newsletter CTAs |
| **Sponsors** | Hashnode has sponsor program |
| **Analytics** | Built-in, more detailed than Dev.to |

---

## Content Formatting

### Structure That Works

```markdown
# Title

[Compelling hook — why should they care?]

## Table of Contents (for long posts)
- [Section 1](#section-1)
- [Section 2](#section-2)

## The Problem

[What pain point are you solving?]

## The Solution

[Your approach, with code examples]

### Code Example

```language
// Well-commented code
const example = "explained";
```

## Step-by-Step

1. **Step one** — Explanation
2. **Step two** — Explanation
3. **Step three** — Explanation

## Common Pitfalls

[What to watch out for]

## Conclusion

[Summary + CTA]

---

*If you found this helpful, [follow me](https://github.com/jonathimer/devmarketing-skills/tree/main/skills/dev-to-hashnode/link) for more content about [topic].*
```

### Formatting Best Practices

| Element | Guideline |
|---------|-----------|
| **Headers** | Use H2 for sections, H3 for subsections |
| **Code blocks** | Always specify language for syntax highlighting |
| **Images** | Use descriptive alt text, compress for speed |
| **Links** | Descriptive text, not "click here" |
| **Length** | 1000-2500 words performs best |
| **Paragraphs** | Keep short, 2-3 sentences max |
| **Lists** | Use liberally for scannability |

---

## Building Followers

### Consistency Strategy

| Frequency | Result |
|-----------|--------|
| 4+ posts/month | Rapid follower growth |
| 2-3 posts/month | Steady growth |
| 1 post/month | Slow but sustainable |
| Sporadic | Minimal follower retention |

### Engagement Tactics

| Tactic | Why it works |
|--------|--------------|
| Reply to every comment | Algorithm boost + relationship building |
| Comment on others' posts | Visibility + community |
| Follow relevant authors | Often reciprocated |
| Share on social media | Drives external traffic |
| Link between your posts | Keeps readers on your content |
| Create series | Encourages following for updates |

### Bio and Profile Optimization

**Dev.to profile**:
- Clear profile photo
- Bio with what you write about
- Link to your main site
- List your expertise areas

**Hashnode profile**:
- Custom domain setup
- Newsletter enabled
- Social links populated
- Blog name and tagline set

---

## Platform-Specific Do's and Don'ts

### Do's

1. **Do** set canonical URLs to protect your SEO
2. **Do** use platform-specific formatting (embeds, etc.)
3. **Do** engage with comments within 24 hours
4. **Do** cross-post to both platforms
5. **Do** use series for related content
6. **Do** optimize cover images for each platform
7. **Do** include a CTA at the end

### Don'ts

1. **Don't** post identical content without canonical URLs
2. **Don't** ignore comments
3. **Don't** use only self-promotional content
4. **Don't** neglect tags — they're discovery mechanisms
5. **Don't** forget mobile readability
6. **Don't** publish unfinished drafts
7. **Don't** keyword stuff your content

---

## Analytics and Iteration

### Dev.to Dashboard

| Metric | What it tells you |
|--------|-------------------|
| Views | Reach/impressions |
| Reactions | Engagement quality |
| Comments | Discussion value |
| Reading time | Content depth |
| Followers from post | Conversion rate |

### Hashnode Analytics

| Metric | What it tells you |
|--------|-------------------|
| Total views | Reach |
| Unique visitors | Audience size |
| Read ratio | Completion rate |
| Time on page | Engagement depth |
| Referrers | Traffic sources |
| Newsletter signups | List growth |

### What to Optimize

| Low metric | Try this |
|------------|----------|
| Low views | Better title, different tags |
| Low reactions | More engaging opening |
| Low comments | End with a question |
| High bounce | Better structure, hook |
| Low followers | Stronger CTA, series |

---

## Tools

| Tool | Use case |
|------|----------|
| **[Octolens](https://octolens.com)** | Monitor Dev.to and Hashnode for mentions of your topic, competitors, and trends. Find popular content to learn from. |
| **Hemingway Editor** | Improve readability |
| **Carbon** | Beautiful code screenshots |
| **Unsplash** | Free cover images |
| **Canva** | Custom cover image design |
| **Grammarly** | Catch errors before publishing |

---

## Content Calendar Template

| Week | Dev.to | Hashnode | Topic |
|------|--------|----------|-------|
| 1 | Publish | Cross-post (day 2) | Tutorial |
| 2 | Cross-post | Publish | Deep dive |
| 3 | Publish | Cross-post (day 2) | Listicle |
| 4 | Cross-post | Publish | Opinion/experience |

---

## Related Skills

- `developer-audience-context` — Know who you're writing for
- `hacker-news-strategy` — Drive traffic from HN to your posts
- `reddit-engagement` — Share posts in relevant subreddits
- `github-presence` — Link from READMEs to your content
- `x-devs` — Promote posts on Twitter/X

## Limitations

- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.


---
name: devcontainer-setup
description: Creates devcontainers with Claude Code, language-specific tooling (Python/Node/Rust/Go), and persistent volumes. Use when adding devcontainer support to a project, setting up isolated development environments, or configuring sandboxed Claude Code workspaces.
risk: safe
source: vibeship-spawner-skills (Apache 2.0)
date_added: 2026-03-06
---

# Devcontainer Setup Skill

Creates a pre-configured devcontainer with Claude Code and language-specific tooling.

## When to Use
- User asks to "set up a devcontainer" or "add devcontainer support"
- User wants a sandboxed Claude Code development environment
- User needs isolated development environments with persistent configuration

## When NOT to Use

- User already has a devcontainer configuration and just needs modifications
- User is asking about general Docker or container questions
- User wants to deploy production containers (this is for development only)

## Workflow

```mermaid
flowchart TB
    start([User requests devcontainer])
    recon[1. Project Reconnaissance]
    detect[2. Detect Languages]
    generate[3. Generate Configuration]
    write[4. Write files to .devcontainer/]
    done([Done])

    start --> recon
    recon --> detect
    detect --> generate
    generate --> write
    write --> done
```

## Phase 1: Project Reconnaissance

### Infer Project Name

Check in order (use first match):

1. `package.json` → `name` field
2. `pyproject.toml` → `project.name`
3. `Cargo.toml` → `package.name`
4. `go.mod` → module path (last segment after `/`)
5. Directory name as fallback

Convert to slug: lowercase, replace spaces/underscores with hyphens.

### Detect Language Stack

| Language | Detection Files |
|----------|-----------------|
| Python | `pyproject.toml`, `*.py` |
| Node/TypeScript | `package.json`, `tsconfig.json` |
| Rust | `Cargo.toml` |
| Go | `go.mod`, `go.sum` |

### Multi-Language Projects

If multiple languages are detected, configure all of them in the following priority order:

1. **Python** - Primary language, uses Dockerfile for uv + Python installation
2. **Node/TypeScript** - Uses devcontainer feature
3. **Rust** - Uses devcontainer feature
4. **Go** - Uses devcontainer feature

For multi-language `postCreateCommand`, chain all setup commands:
```
uv run /opt/post_install.py && uv sync && npm ci
```

Extensions and settings from all detected languages should be merged into the configuration.

## Phase 2: Generate Configuration

Start with base templates from `resources/` directory. Substitute:

- `{{PROJECT_NAME}}` → Human-readable name (e.g., "My Project")
- `{{PROJECT_SLUG}}` → Slug for volumes (e.g., "my-project")

Then apply language-specific modifications below.

## Base Template Features

The base template includes:

- **Claude Code** with marketplace plugins (anthropics/skills, trailofbits/skills, trailofbits/skills-curated)
- **Python 3.13** via uv (fast binary download)
- **Node 22** via fnm (Fast Node Manager)
- **ast-grep** for AST-based code search
- **Network isolation tools** (iptables, ipset) with NET_ADMIN capability
- **Modern CLI tools**: ripgrep, fd, fzf, tmux, git-delta

---

## Language-Specific Sections

### Python Projects

**Detection:** `pyproject.toml`, `requirements.txt`, `setup.py`, or `*.py` files

**Dockerfile additions:**

The base Dockerfile already includes Python 3.13 via uv. If a different version is required (detected from `pyproject.toml`), modify the Python installation:

```dockerfile
# Install Python via uv (fast binary download, not source compilation)
RUN uv python install <version> --default
```

**devcontainer.json extensions:**

Add to `customizations.vscode.extensions`:
```json
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"
```

Add to `customizations.vscode.settings`:
```json
"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
  "editor.defaultFormatter": "charliermarsh.ruff",
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}
```

**postCreateCommand:**
If `pyproject.toml` exists, chain commands:
```
rm -rf .venv && uv sync && uv run /opt/post_install.py
```

---

### Node/TypeScript Projects

**Detection:** `package.json` or `tsconfig.json`

**No Dockerfile additions needed:** The base template includes Node 22 via fnm (Fast Node Manager).

**devcontainer.json extensions:**

Add to `customizations.vscode.extensions`:
```json
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
```

Add to `customizations.vscode.settings`:
```json
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
  "source.fixAll.eslint": "explicit"
}
```

**postCreateCommand:**
Detect package manager from lockfile and chain with base command:
- `pnpm-lock.yaml` → `uv run /opt/post_install.py && pnpm install --frozen-lockfile`
- `yarn.lock` → `uv run /opt/post_install.py && yarn install --frozen-lockfile`
- `package-lock.json` → `uv run /opt/post_install.py && npm ci`
- No lockfile → `uv run /opt/post_install.py && npm install`

---

### Rust Projects

**Detection:** `Cargo.toml`

**Features to add:**

```json
"ghcr.io/devcontainers/features/rust:1": {}
```

**devcontainer.json extensions:**

Add to `customizations.vscode.extensions`:
```json
"rust-lang.rust-analyzer",
"tamasfe.even-better-toml"
```

Add to `customizations.vscode.settings`:
```json
"[rust]": {
  "editor.defaultFormatter": "rust-lang.rust-analyzer"
}
```

**postCreateCommand:**
If `Cargo.lock` exists, use locked builds:
```
uv run /opt/post_install.py && cargo build --locked
```
If no lockfile, use standard build:
```
uv run /opt/post_install.py && cargo build
```

---

### Go Projects

**Detection:** `go.mod`

**Features to add:**

```json
"ghcr.io/devcontainers/features/go:1": {
  "version": "latest"
}
```

**devcontainer.json extensions:**

Add to `customizations.vscode.extensions`:
```json
"golang.go"
```

Add to `customizations.vscode.settings`:
```json
"[go]": {
  "editor.defaultFormatter": "golang.go"
},
"go.useLanguageServer": true
```

**postCreateCommand:**
```
uv run /opt/post_install.py && go mod download
```

---

## Reference Material

For additional guidance, see:
- `references/dockerfile-best-practices.md` - Layer optimization, multi-stage builds, architecture support
- `references/features-vs-dockerfile.md` - When to use devcontainer features vs custom Dockerfile

---

## Adding Persistent Volumes

Pattern for new mounts in `devcontainer.json`:

```json
"mounts": [
  "source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<container-path>,type=volume"
]
```

Common additions:
- `source={{PROJECT_SLUG}}-cargo-${devcontainerId},target=/home/vscode/.cargo,type=volume` (Rust)
- `source={{PROJECT_SLUG}}-go-${devcontainerId},target=/home/vscode/go,type=volume` (Go)

---

## Output Files

Generate these files in the project's `.devcontainer/` directory:

1. `Dockerfile` - Container build instructions
2. `devcontainer.json` - VS Code/devcontainer configuration
3. `post_install.py` - Post-creation setup script
4. `.zshrc` - Shell configuration
5. `install.sh` - CLI helper for managing the devcontainer (`devc` command)

---

## Validation Checklist

Before presenting files to the user, verify:

1. All `{{PROJECT_NAME}}` placeholders are replaced with the human-readable name
2. All `{{PROJECT_SLUG}}` placeholders are replaced with the slugified name
3. JSON syntax is valid in `devcontainer.json` (no trailing commas, proper nesting)
4. Language-specific extensions are added for all detected languages
5. `postCreateCommand` includes all required setup commands (chained with `&&`)

---

## User Instructions

After generating, inform the user:

1. How to start: "Open in VS Code and select 'Reopen in Container'"
2. Alternative: `devcontainer up --workspace-folder .`
3. CLI helper: Run `.devcontainer/install.sh self-install` to add the `devc` command to PATH

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.