constella 0.1.0

package/skills/README.md

@@ -0,0 +1,57 @@
+# Constella skills — agent knowledge base
+
+A curated, research-backed reference library for AI agents working on Constella. **182 skills**, each grounded in official documentation, repositories, and standards — every URL verified live (`verified: 2026-06-16`).
+
+## What this is — and is not
+- **Is:** knowledge agents *consult* before/while building — official docs, install commands, core concepts, best practices, pitfalls, and an executable process playbook.
+- **Is not:** the runtime `.claude/skills/` directory (those are per-org executable procedures indexed by `src/server/sync.ts`). This library lives at the repo root, **outside** the org workspace jail, and is **not** auto-indexed into the app DB/UI.
+
+## How an agent uses it
+1. Identify the task **domain** (e.g. backend, security, CSS) and the project's declared **stack** (from `.claude/CLAUDE.md`).
+2. Open the matching `SKILL.md`. Stack lookup is deterministic — `orm: Drizzle` → [`stacks/orm/drizzle/SKILL.md`](stacks/orm/drizzle/SKILL.md). Full map below and in [COVERAGE.md](COVERAGE.md).
+3. Read `Further reading` / `reference.md` only if you need depth (progressive disclosure).
+4. Trust the **Official sources**. If `verified:` is stale, re-check before relying on version-specific details.
+5. For the `process/` skills, follow the numbered **Procedure** — they are executable playbooks, not background reading.
+
+## Two formats (hybrid)
+- **Knowledge `SKILL.md`** — YAML frontmatter (`name`, `description`, `domain`, `category`, `tags`, `official_sources`, `verified`) + sections Overview / Official sources / Install / Core concepts / Best practices / Common pitfalls / Examples / Further reading / Related. Used by `meta/`, `engineering/`, `design/`, `languages/`, `stacks/`, `references/`.
+- **Runtime `# Skill —` procedure** — `**Trigger:**` + When to use / Procedure / Quality & validation / Failure handling. Matches the existing `.claude/skills/` convention so a process skill could be promoted into a workspace later. Used by `process/`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full templates and the non-negotiable trust rules (official sources only, never invent, cite & summarize never copy).
+
+## Taxonomy
+| Group | Count | What's inside |
+|---|---|---|
+| [`process/`](process/) | 15 | Build it right **before** coding: discovery, framing, idea→product, mocks & flows, architecture-first, requirements→specs, specs→issues, sprints, prioritization (MoSCoW/RICE), app planning, UX/nav validation, security-by-design, testing-before-done, ADRs, code/perf/security review |
+| [`engineering/`](engineering/) | 32 | `security/` (OWASP Top 10, ASVS, appsec, auth/sessions, secrets, supply chain) · `architecture/` (system design, patterns, API design, data modeling, caching, queues, scalability) · `performance/` · `testing/` · `frontend/` · `backend/` · `practices/` (clean code, review, refactoring, git, optimization) |
+| [`design/`](design/) | 9 | UI/UX principles, design systems, CSS techniques, graphic design, animation/motion, microinteractions, gradients, color & typography, responsive layout |
+| [`languages/`](languages/) | 15 | Per-language techniques for every catalog language (TypeScript … Dart) |
+| [`stacks/`](stacks/) | 98 | One skill per catalog option across `runtime/ frontend/ meta/ backend/ database/ orm/ styling/ container/ infra/ queue/ auth/` |
+| [`references/`](references/) | 10 | External product/AI-UI references distilled: WebLLM, AI SDK Elements, attachments UI, AI tool UI, SaaS landing patterns, Codrops animation, component galleries, shadcn/Tailwind theming, React component libraries, gradients |
+| [`meta/`](meta/) | 3 | How to author agent skills (frontmatter spec, progressive disclosure) |
+
+Machine-readable manifest: [INDEX.json](INDEX.json) (one object per skill: name, path, domain, category, description, tags, official_sources, verified). Coverage report + full stack table: [COVERAGE.md](COVERAGE.md).
+
+## Stack lookup (catalog option → skill)
+Every selectable catalog option in [`src/data/stack-catalog.ts`](../src/data/stack-catalog.ts) resolves to a skill (**113/113**, "None" excluded). `Redis` is canonical at [`stacks/database/redis`](stacks/database/redis/SKILL.md) with a queue-focused cross-link at [`stacks/queue/redis`](stacks/queue/redis/SKILL.md).
+
+- **language** → `languages/<slug>` (typescript, javascript, python, go, rust, java, kotlin, csharp, ruby, php, elixir, swift, cpp, scala, dart)
+- **runtime** → `stacks/runtime/<slug>` (node, bun, deno, python3, pypy, jvm, dotnet, beam)
+- **frontend** → `stacks/frontend/<slug>` (react, vue, svelte, angular, solidjs, preact, qwik, lit, htmx, alpine)
+- **meta** → `stacks/meta/<slug>` (nextjs, nuxt, remix, sveltekit, astro, gatsby, vite)
+- **backend** → `stacks/backend/<slug>` (nestjs, fastify, express, hono, koa, django, flask, fastapi, spring-boot, laravel, rails, gin, fiber, actix, phoenix, aspnet-core, adonisjs)
+- **database** → `stacks/database/<slug>` (postgresql, mysql, mariadb, sqlite, mongodb, redis, cockroachdb, cassandra, dynamodb, supabase, planetscale, neon)
+- **orm** → `stacks/orm/<slug>` (prisma, drizzle, typeorm, sequelize, sqlalchemy, django-orm, mongoose, knex, diesel, gorm)
+- **styling** → `stacks/styling/<slug>` (tailwind, css-modules, styled-components, sass, vanilla-extract, unocss, shadcn-ui, mui, chakra-ui)
+- **container** → `stacks/container/<slug>` (docker, podman, containerd)
+- **infra** → `stacks/infra/<slug>` (tailscale, cloudflare, vercel, netlify, fly-io, railway, aws, gcp, kubernetes)
+- **queue** → `stacks/queue/<slug>` (redis, bullmq, rabbitmq, kafka, nats, celery)
+- **auth** → `stacks/auth/<slug>` (authjs, clerk, lucia, supabase-auth, keycloak, auth0, passport)
+
+The full option-by-option table (with ✅ presence checks) is in [COVERAGE.md](COVERAGE.md).
+
+## Relationship to runtime skills
+To make a piece of this knowledge executable inside an org workspace, author a separate `# Skill — <name>` file under that workspace's `.claude/skills/` (the indexed, runtime format). This library is the source material; it is not wired into the scaffold.
+
+## Maintenance
+Sources drift. The `verified:` date on each knowledge skill enables a staleness sweep. Known volatile entries are flagged in-skill: **Lucia** (now a learning resource, not a maintained library), **PlanetScale/Neon** (evolving products), and the fast-moving AI-UI reference sites. Re-run the URL-integrity check and re-verify before relying on version-specific details past the verified date.

package/skills/design/animation-motion/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: animation-motion
+description: Motion design principles and the Web Animations API for purposeful, performant UI animation; consult when adding transitions or animated feedback.
+domain: design
+category: design
+tags: [animation, motion, web-animations-api, easing, transitions]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API
+  - https://m3.material.io/styles/motion/overview
+verified: 2026-06-16
+---
+
+# Animation & Motion
+
+## Overview
+Motion communicates change, hierarchy, and continuity when used purposefully; the Web Animations API (WAAPI) is the standard scriptable way to create and control animations in JavaScript. MDN documents the API; Material Design 3 motion guidance supplies the principles (easing, duration, transitions). Read this when adding animated feedback, page/element transitions, or coordinated motion.
+
+## Official sources
+- MDN — Web Animations API: https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API
+- Material Design 3 — Motion overview: https://m3.material.io/styles/motion/overview
+- Material Design 3 — Easing and duration: https://m3.material.io/styles/motion/easing-and-duration/tokens-specs
+
+## Core concepts
+- **Element.animate()** — shortcut that creates and plays an animation on an element and returns an `Animation` object (MDN WAAPI).
+- **KeyframeEffect** — describes the animatable properties/values (keyframes) plus timing options (MDN WAAPI).
+- **Animation** — object exposing playback controls (play, pause, reverse, finish) and a timeline (MDN WAAPI).
+- **AnimationTimeline / DocumentTimeline** — the time source; `document.timeline` is the default (MDN WAAPI).
+- **Element.getAnimations() / Document.getAnimations()** — enumerate animations affecting an element or document (MDN WAAPI).
+- **Easing and duration** — motion tokens that define acceleration curves and timing for consistent, natural movement (M3 easing and duration).
+
+## Best practices
+- Use `Element.animate()` for imperative, controllable animations and `getAnimations()` to coordinate or cancel them (MDN WAAPI).
+- Apply system easing/duration tokens so motion is consistent across the product rather than ad-hoc per component (M3 easing and duration).
+- Animate compositor-friendly properties (transform, opacity) for smooth, performant motion.
+- Make motion purposeful — reinforce a state change or spatial relationship, not decoration (M3 motion overview).
+
+## Common pitfalls
+- Long or non-interruptible animations that block the user → keep durations short and let `Animation` controls pause/reverse (MDN WAAPI; M3 duration).
+- Inconsistent easing per component → centralize on shared easing/duration tokens (M3 easing and duration).
+- Ignoring reduced-motion users → respect `prefers-reduced-motion` and scale back non-essential animation.
+
+## Examples
+```js
+// WAAPI: fade + slide in, then control playback
+const anim = card.animate(
+  [{ opacity: 0, transform: 'translateY(8px)' }, { opacity: 1, transform: 'none' }],
+  { duration: 200, easing: 'cubic-bezier(0.2, 0, 0, 1)', fill: 'both' }
+);
+anim.onfinish = () => card.classList.add('is-ready');
+// Respect user preference
+if (matchMedia('(prefers-reduced-motion: reduce)').matches) anim.finish();
+```
+
+## Further reading
+- MDN WAAPI guides and interfaces: https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API
+- M3 motion specs and tokens: https://m3.material.io/styles/motion/overview
+
+## Related skills
+- ../microinteractions — small animated feedback cues built on these APIs
+- ../css-techniques — transitions and keyframes as a declarative alternative

package/skills/design/color-and-typography/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: color-and-typography
+description: Color systems, type scale, and WCAG contrast ratios for legible, accessible UI; consult when defining palettes, text styles, or checking contrast.
+domain: design
+category: design
+tags: [color, typography, contrast, wcag, accessibility, type-scale]
+official_sources:
+  - https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+  - https://m3.material.io/styles/color/system/overview
+verified: 2026-06-16
+---
+
+# Color & Typography
+
+## Overview
+Color and typography decisions determine whether an interface is legible and accessible. WCAG 2.2 defines the minimum contrast ratios text must meet; Material Design 3 defines a role-based color system and a tokenized type scale. Read this when building a palette, defining text styles, or validating that foreground/background pairs are readable.
+
+## Official sources
+- W3C WCAG 2.2 — Understanding Contrast (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+- Material Design 3 — Color system overview: https://m3.material.io/styles/color/system/overview
+- Material Design 3 — Type scale tokens: https://m3.material.io/styles/typography/type-scale-tokens
+
+## Core concepts
+- **Contrast ratio (AA)** — normal text needs at least 4.5:1; large-scale text needs at least 3:1 (WCAG 2.2 SC 1.4.3).
+- **Large text definition** — at least 18pt, or 14pt bold, qualifies for the 3:1 threshold (WCAG 2.2 SC 1.4.3).
+- **Color roles** — M3 assigns semantic roles (primary, on-primary, surface, etc.) rather than raw colors, so pairs are designed to be legible (M3 color system).
+- **Color schemes** — light/dark schemes derived from a source color keep contrast and harmony consistent (M3 color system).
+- **Type scale** — a tokenized set of named styles (display, headline, title, body, label) encoding size/weight/line-height (M3 type scale tokens).
+- **Typographic hierarchy** — using the scale to signal importance and reading order.
+
+## Best practices
+- Verify every text/background pair meets at least 4.5:1 (normal) or 3:1 (large) for WCAG AA (WCAG 2.2 SC 1.4.3).
+- Pair color roles deliberately (e.g., `on-primary` over `primary`) so contrast is built into the system, not guessed (M3 color roles).
+- Define both light and dark schemes from the same source color to preserve contrast across modes (M3 color system).
+- Use the type scale tokens for consistent hierarchy instead of arbitrary font sizes (M3 type scale tokens).
+
+## Common pitfalls
+- Choosing colors by aesthetics alone and failing AA contrast → measure the ratio and adjust lightness (WCAG 2.2 SC 1.4.3).
+- Assuming large text needs 4.5:1 → it only needs 3:1 once it meets the large-text size threshold (WCAG 2.2 SC 1.4.3).
+- Hardcoding colors per component instead of using semantic roles → use role tokens so theming and dark mode stay legible (M3 color roles).
+
+## Examples
+```css
+/* Role-based tokens with a verified-contrast pairing */
+:root {
+  --color-primary: #4a3aff;       /* background */
+  --color-on-primary: #ffffff;    /* text: meets >= 4.5:1 for normal text */
+}
+.cta { background: var(--color-primary); color: var(--color-on-primary); }
+/* Type scale token example */
+.headline-large { font-size: 2rem; line-height: 2.5rem; font-weight: 400; }
+```
+
+## Further reading
+- WCAG 2.2 contrast understanding doc: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+- M3 color & typography styles: https://m3.material.io/styles/color/system/overview
+
+## Related skills
+- ../design-systems — encoding color roles and type scale as tokens
+- ../graphic-design-basics — applying contrast and hierarchy in layout

package/skills/design/css-techniques/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: css-techniques
+description: Modern CSS layout and styling — grid, flexbox, container queries, custom properties; consult when building responsive, maintainable styles.
+domain: design
+category: design
+tags: [css, grid, flexbox, container-queries, custom-properties]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/CSS
+  - https://web.dev/learn/css
+verified: 2026-06-16
+---
+
+# CSS Techniques
+
+## Overview
+Modern CSS provides dedicated layout systems (Grid for two dimensions, Flexbox for one), element-aware responsiveness (container queries), and reusable values (custom properties), replacing older float and hack-based approaches. MDN is the canonical reference; web.dev's Learn CSS is the official structured course. Read this when laying out pages and components or modernizing legacy stylesheets.
+
+## Official sources
+- MDN CSS reference: https://developer.mozilla.org/en-US/docs/Web/CSS
+- web.dev — Learn CSS: https://web.dev/learn/css
+
+## Core concepts
+- **Box model** — every element is a box of content, padding, border, and margin; `box-sizing` controls how width is computed (MDN/web.dev Box Model).
+- **Flexbox** — one-dimensional layout distributing space along a single axis (row or column) (MDN Flexbox; web.dev Flexbox).
+- **Grid** — two-dimensional layout using tracks, lines, and named areas for rows and columns simultaneously (MDN Grid; web.dev Grid).
+- **Container queries** — style elements based on the size (and style) of their container rather than the viewport (MDN Container Queries; web.dev module 38).
+- **Custom properties** — `--name` variables that cascade and can be read at runtime for theming (web.dev Custom Properties).
+- **Cascade, specificity, inheritance** — the rules that decide which declaration wins and which values pass to children (web.dev Cascade/Specificity/Inheritance).
+- **Logical properties** — writing-mode-aware properties (e.g. `margin-inline`) that adapt to text direction (web.dev Logical Properties).
+
+## Best practices
+- Choose Flexbox for one-axis distribution and Grid for two-axis layout instead of forcing one tool to do both (MDN layout modules).
+- Use container queries so components adapt to where they are placed, not just the viewport width (MDN Container Queries).
+- Drive theming and repeated values through custom properties to avoid magic numbers (web.dev Custom Properties).
+- Prefer logical properties (`inline`/`block`) for internationalized, direction-agnostic layouts (web.dev Logical Properties).
+
+## Common pitfalls
+- Using absolute positioning or floats for layout → use Grid/Flexbox, which handle alignment and spacing natively (MDN layout).
+- Fighting the cascade with `!important` → resolve via specificity and source order per the cascade rules (web.dev Cascade).
+- Assuming viewport media queries suffice for reusable components → add container queries so a component reflows in any context (MDN Container Queries).
+
+## Examples
+```css
+/* Responsive card grid: auto-fit tracks with a minimum width */
+.grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap: 1rem; }
+
+/* Container query: stack below the container's own breakpoint */
+.card-wrap { container-type: inline-size; }
+@container (max-width: 24rem) { .card { flex-direction: column; } }
+```
+
+## Further reading
+- MDN CSS layout guides: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout
+- web.dev Learn CSS full module list: https://web.dev/learn/css
+
+## Related skills
+- ../responsive-layout — fluid and intrinsic layout strategies built on these primitives
+- ../gradients — modern background/image techniques in CSS

package/skills/design/design-systems/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: design-systems
+description: Design tokens, reusable components, and governance for scalable UI; consult when building or maintaining a shared component library.
+domain: design
+category: design
+tags: [design-systems, design-tokens, components, governance, material-design]
+official_sources:
+  - https://m3.material.io/foundations/design-tokens
+  - https://www.designsystems.com/
+verified: 2026-06-16
+---
+
+# Design Systems
+
+## Overview
+A design system is a shared source of truth that pairs design tokens, reusable components, and usage guidelines so designers and engineers ship consistent UI at scale. Material Design 3 (Google's open-source system) defines the token model and component foundations; designsystems.com (Figma's publication) covers process, operations, and governance. Read this when starting, scaling, or governing a component library.
+
+## Official sources
+- Material Design 3 — Design tokens: https://m3.material.io/foundations/design-tokens
+- Material Design 3 — Foundations: https://m3.material.io/foundations
+- DesignSystems.com (by Figma): https://www.designsystems.com/
+
+## Core concepts
+- **Design tokens** — named, tokenized values that are the building blocks of UI and are used identically in design, tooling, and code (M3 design tokens).
+- **Reference tokens** — the full set of available raw tokenized values, e.g. `md.ref.palette.secondary200` (M3 glossary).
+- **System tokens** — semantic roles/choices that make up the system: color, typography, elevation, shape (M3 glossary).
+- **Component tokens** — design attributes scoped to a component, such as a button container's color (M3 glossary).
+- **Components** — reusable building blocks (buttons, fields, cards) wired to system tokens so a token change propagates everywhere.
+- **Foundations** — cross-cutting bases like accessibility, layout, and interaction patterns that underpin every component (M3 foundations).
+- **Governance** — the operations and process layer (contribution, versioning, ownership) covered under Design Operations on designsystems.com.
+
+## Best practices
+- Layer tokens reference → system → component so raw values stay decoupled from semantic intent (M3 token tiers).
+- Use one token set across design tools and code so a single change updates designs and production together (M3 design tokens).
+- Bake accessibility into foundations (contrast, focus, hit targets) rather than retrofitting per component (M3 foundations).
+- Establish governance — contribution model, ownership, and versioning — so the system evolves without fragmenting (designsystems.com Design Operations).
+
+## Common pitfalls
+- Hardcoding raw hex/spacing values in components → reference system tokens so themes and rebrands cascade (M3 token tiers).
+- Treating the library as "done" with no governance → assign owners and a contribution/versioning process (designsystems.com).
+- Building components before defining tokens and foundations → settle tokens and accessibility bases first, then compose components.
+
+## Examples
+```css
+/* System tokens (semantic) reference raw palette tokens */
+:root {
+  --md-sys-color-primary: var(--md-ref-palette-primary40);
+  --md-sys-color-on-primary: var(--md-ref-palette-primary100);
+}
+/* Component consumes only system tokens */
+.button { background: var(--md-sys-color-primary); color: var(--md-sys-color-on-primary); }
+```
+
+## Further reading
+- M3 customization & theming: https://m3.material.io/foundations/customization
+- designsystems.com articles on tokens, ops, and governance: https://www.designsystems.com/
+
+## Related skills
+- ../color-and-typography — color roles and type scale that tokens encode
+- ../ui-ux-principles — consistency and standards realized via shared components

package/skills/design/gradients/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: gradients
+description: Tasteful CSS gradients — linear, radial, conic, repeating, and layered meshes; consult when adding depth or color washes to backgrounds.
+domain: design
+category: design
+tags: [css, gradients, backgrounds, color, mesh]
+official_sources:
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_images/Using_CSS_gradients
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/gradient
+verified: 2026-06-16
+---
+
+# Gradients
+
+## Overview
+CSS gradients are image-type values that transition smoothly between colors without raster assets, used for backgrounds, fills, and layered "mesh" effects. They are widely available (baseline since 2015). MDN documents the gradient data type and a practical usage guide. Read this when adding color washes, subtle depth, or decorative backgrounds in CSS.
+
+## Official sources
+- MDN — Using CSS gradients (guide): https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_images/Using_CSS_gradients
+- MDN — `<gradient>` data type: https://developer.mozilla.org/en-US/docs/Web/CSS/gradient
+
+## Core concepts
+- **linear-gradient()** — colors progress along a straight line at a given angle or direction (MDN gradient).
+- **radial-gradient()** — colors radiate outward from a center origin (MDN gradient).
+- **conic-gradient()** — colors transition around a center point, useful for pie charts and color wheels (MDN gradient).
+- **Repeating variants** — `repeating-linear-gradient()`, `repeating-radial-gradient()`, `repeating-conic-gradient()` tile a gradient to fill the area (MDN gradient).
+- **Color stops & hints** — positions control where colors land; hints adjust the midpoint of interpolation (MDN Using gradients).
+- **Layering / meshes** — multiple gradients stacked in one `background` (comma-separated) create mesh-like blends (MDN Using gradients).
+- **Premultiplied interpolation** — gradients interpolate in alpha-premultiplied space to avoid muddy gray transitions (MDN gradient).
+
+## Best practices
+- Stack several positioned radial gradients to approximate a soft "mesh" without images (MDN Using gradients — overlaying gradients).
+- Place explicit color stops to control band placement and create hard lines when desired (MDN Using gradients).
+- Use `background-blend-mode` to mix layered gradients for richer results (MDN Using gradients).
+- When fading to transparent, beware default interpolation muddiness — premultiplied space mitigates it, but verify the midpoint (MDN gradient).
+
+## Common pitfalls
+- Fading a color to `transparent` and getting a gray haze → fade to the same hue with `0` alpha (e.g., `rgb(0 0 0 / 0)`) instead of the keyword (MDN gradient interpolation note).
+- Overusing high-contrast gradients behind text → keep washes subtle and check contrast of overlaid content.
+- Forgetting repeating gradients exist for patterns → use `repeating-*` instead of manually duplicating stops (MDN gradient).
+
+## Examples
+```css
+/* Layered "mesh": multiple soft radial gradients stacked */
+.hero {
+  background:
+    radial-gradient(40rem 40rem at 10% 20%, #6d5efc55, transparent 60%),
+    radial-gradient(30rem 30rem at 90% 30%, #00d4ff44, transparent 60%),
+    linear-gradient(160deg, #0b1020, #131a33);
+}
+```
+
+## Further reading
+- MDN Using CSS gradients (overlaying, hints, blending): https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_images/Using_CSS_gradients
+- MDN `<gradient>` reference: https://developer.mozilla.org/en-US/docs/Web/CSS/gradient
+
+## Related skills
+- ../css-techniques — backgrounds and modern CSS context
+- ../color-and-typography — choosing harmonious, accessible colors

package/skills/design/graphic-design-basics/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: graphic-design-basics
+description: Visual hierarchy, grids, contrast, and spacing fundamentals for UI; consult when composing layouts and establishing visual order.
+domain: design
+category: design
+tags: [visual-hierarchy, grids, contrast, spacing, layout]
+official_sources:
+  - https://m3.material.io/foundations
+  - https://developer.mozilla.org/en-US/docs/Web/CSS
+verified: 2026-06-16
+---
+
+# Graphic Design Basics
+
+## Overview
+Graphic design basics for interfaces are the visual mechanics that guide attention: hierarchy, grids/layout, contrast, and consistent spacing. Material Design 3 foundations codify layout, spacing, and accessible contrast as system-level guidance, while MDN documents the CSS properties that implement them. Read this when a layout feels flat, cluttered, or hard to scan.
+
+## Official sources
+- Material Design 3 — Foundations: https://m3.material.io/foundations
+- MDN CSS reference: https://developer.mozilla.org/en-US/docs/Web/CSS
+
+## Core concepts
+- **Visual hierarchy** — using size, weight, color, and position to signal what matters most and the order to read it (M3 foundations: layout/typography).
+- **Grids and layout** — a consistent column/row structure that aligns content and creates rhythm (M3 foundations: layout).
+- **Spacing** — predictable gaps between and within elements (margins, padding, gap) that group related items and separate unrelated ones (MDN spacing properties; M3 layout).
+- **Contrast** — differences in value/color/scale that make foreground readable and draw the eye; tied to accessible color (M3 foundations: accessibility).
+- **Alignment** — shared edges and baselines that make composition feel intentional, expressible via CSS box alignment (MDN alignment).
+- **Typographic scale** — a stepped set of sizes/weights that encodes hierarchy in text (M3 type/foundations).
+
+## Best practices
+- Establish hierarchy first: decide the primary, secondary, and tertiary elements, then assign size/weight/color accordingly (M3 layout/typography).
+- Use a consistent spacing system (multiples of a base unit) rather than ad-hoc pixel values to create rhythm (M3 layout; MDN spacing).
+- Ground contrast choices in accessibility so hierarchy is legible to all users (M3 accessibility foundation).
+- Align elements to a shared grid; alignment is a low-cost way to make a layout look composed (M3 layout).
+
+## Common pitfalls
+- Everything emphasized equally (all bold/large) → establish one clear focal point and demote the rest (M3 hierarchy).
+- Random, inconsistent spacing → adopt a spacing scale and apply it systematically (M3 layout; MDN `gap`/`margin`).
+- Low-contrast decorative text that fails legibility → verify against accessible contrast guidance (M3 accessibility; see color-and-typography skill).
+
+## Examples
+```css
+/* Spacing scale via custom properties + grid rhythm */
+:root { --space-1: .25rem; --space-2: .5rem; --space-4: 1rem; --space-8: 2rem; }
+.section { display: grid; gap: var(--space-8); }
+.stack > * + * { margin-block-start: var(--space-4); } /* consistent vertical rhythm */
+```
+
+## Further reading
+- M3 foundations (layout, accessibility): https://m3.material.io/foundations
+- MDN box alignment & spacing: https://developer.mozilla.org/en-US/docs/Web/CSS
+
+## Related skills
+- ../color-and-typography — type scale and accessible contrast detail
+- ../responsive-layout — translating grids into responsive layouts

package/skills/design/microinteractions/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: microinteractions
+description: Trigger-feedback pairs, state cues, and transitions that confirm actions; consult when designing button states, validation, and small feedback moments.
+domain: design
+category: design
+tags: [microinteractions, feedback, transitions, state, ux]
+official_sources:
+  - https://www.nngroup.com/articles/microinteractions/
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/transition
+verified: 2026-06-16
+---
+
+# Microinteractions
+
+## Overview
+Microinteractions are small, single-purpose trigger-feedback pairs that confirm an action or communicate a state change through contextual UI changes. Nielsen Norman Group defines the concept; MDN documents CSS transitions, a primary way to implement smooth state feedback. Read this when designing button/hover/focus states, form validation, toggles, loading, or any small "did that work?" moment.
+
+## Official sources
+- Nielsen Norman Group — Microinteractions: https://www.nngroup.com/articles/microinteractions/
+- MDN — CSS transition: https://developer.mozilla.org/en-US/docs/Web/CSS/transition
+
+## Core concepts
+- **Microinteraction** — a trigger-feedback pair where feedback is a narrowly targeted, contextual (usually visual) response to the trigger (NN/g).
+- **Trigger** — what starts it: a user action (click, gesture, voice) or a change in system state (NN/g).
+- **Feedback** — the small, highly contextual UI change that responds to the trigger, often visual, sometimes auditory (NN/g).
+- **State cues** — visible distinctions between default, hover, focus, active, disabled, loading, success, and error states.
+- **Transitions** — `transition` smoothly interpolates between state property values over a duration, easing, and optional delay (MDN transition).
+
+## Best practices
+- Pair every meaningful trigger with immediate, proportionate feedback so the user knows it registered (NN/g).
+- Keep microinteractions single-purpose and narrowly targeted rather than bundling multiple effects (NN/g).
+- Use CSS transitions for smooth, declarative state changes and list only the properties you intend to animate (MDN transition).
+- Cover the full state matrix (hover, focus-visible, active, disabled, loading, error/success) so feedback is complete and accessible.
+
+## Common pitfalls
+- Transitioning `all` → name specific properties to avoid janky, unintended animations (MDN transition).
+- Silent triggers with no feedback (e.g., a submit that appears to do nothing) → add an immediate visual response (NN/g).
+- Overloading one microinteraction with several effects → keep it focused on a single, contextual response (NN/g).
+
+## Examples
+```css
+/* State cues with a scoped transition */
+.btn {
+  background: var(--bg);
+  transition: background-color 150ms ease, box-shadow 150ms ease;
+}
+.btn:hover { background: var(--bg-hover); }
+.btn:focus-visible { box-shadow: 0 0 0 3px var(--focus-ring); }
+.btn[aria-busy="true"] { opacity: .6; cursor: progress; } /* loading cue */
+```
+
+## Further reading
+- NN/g microinteractions article: https://www.nngroup.com/articles/microinteractions/
+- MDN transition reference: https://developer.mozilla.org/en-US/docs/Web/CSS/transition
+
+## Related skills
+- ../animation-motion — richer scripted motion via the Web Animations API
+- ../ui-ux-principles — "visibility of system status" that feedback fulfills

package/skills/design/responsive-layout/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: responsive-layout
+description: Fluid, breakpoint, and intrinsic layout strategies for any screen; consult when making pages and components adapt across viewports and containers.
+domain: design
+category: design
+tags: [responsive, layout, css-grid, media-queries, container-queries, intrinsic]
+official_sources:
+  - https://web.dev/learn/design/
+  - https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout
+verified: 2026-06-16
+---
+
+# Responsive Layout
+
+## Overview
+Responsive layout makes content adapt gracefully across screen sizes using a mix of fluid units, breakpoints (media queries), and intrinsic techniques where the layout itself flexes without explicit breakpoints. web.dev's Learn Responsive Design is the official course; MDN's Grid module is the canonical reference for the two-dimensional engine that powers intrinsic layouts. Read this when building pages or components that must work everywhere.
+
+## Official sources
+- web.dev — Learn Responsive Design: https://web.dev/learn/design/
+- MDN — CSS Grid Layout: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout
+
+## Core concepts
+- **Media queries** — adapt designs to screen/device characteristics at chosen breakpoints (web.dev — Media queries).
+- **Macro vs. micro layouts** — page-level structure vs. flexible components that can be placed anywhere (web.dev — Macro/Micro layouts).
+- **Intrinsic layout** — let content and the grid decide sizing (e.g., `auto-fit` + `minmax`) so fewer hard breakpoints are needed (MDN Grid; web.dev layout).
+- **Grid tracks, lines, areas** — the structural primitives for two-dimensional responsive layouts (MDN Grid).
+- **`fr`, `minmax()`, `auto-fill`/`auto-fit`** — flexible track sizing that distributes space and wraps automatically (MDN Grid).
+- **Container queries** — components respond to their container's size, complementing viewport media queries (web.dev — Micro layouts / container queries).
+- **Theming & media features** — adapt to preferences like dark mode and reduced motion (web.dev — Theming/Media features).
+
+## Best practices
+- Build components as micro layouts that flex anywhere, rather than assuming a fixed page position (web.dev — Micro layouts).
+- Prefer intrinsic sizing (`repeat(auto-fit, minmax(...))`) to reduce the number of manual breakpoints (MDN Grid).
+- Use media queries for macro page structure and container queries for component-level adaptation (web.dev).
+- Honor user preferences (dark mode, reduced motion) via media features as part of responsiveness (web.dev — Media features/Theming).
+
+## Common pitfalls
+- Pixel-perfect fixed widths that break between breakpoints → use fluid units and `minmax()` so layouts fill the gaps (MDN Grid).
+- Relying only on viewport media queries for reusable components → add container queries so they reflow in any context (web.dev).
+- Designing desktop-first and retrofitting small screens → start from flexible, content-driven layouts (web.dev — Macro layouts).
+
+## Examples
+```css
+/* Intrinsic, breakpoint-light card layout */
+.cards { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(18rem, 1fr)); }
+
+/* Macro layout switch at a deliberate breakpoint */
+@media (min-width: 64rem) {
+  .page { grid-template-columns: 16rem 1fr; } /* sidebar + content */
+}
+```
+
+## Further reading
+- web.dev Learn Responsive Design modules: https://web.dev/learn/design/
+- MDN Grid layout guides: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout
+
+## Related skills
+- ../css-techniques — grid, flexbox, and container query fundamentals
+- ../graphic-design-basics — grid and spacing principles behind layouts

package/skills/design/ui-ux-principles/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ui-ux-principles
+description: Usability heuristics, affordances, and laws of UX to evaluate and design interfaces; consult when reviewing or building user-facing flows.
+domain: design
+category: design
+tags: [usability, heuristics, ux, laws-of-ux, interaction-design]
+official_sources:
+  - https://www.nngroup.com/articles/ten-usability-heuristics/
+  - https://lawsofux.com/
+verified: 2026-06-16
+---
+
+# UI/UX Principles
+
+## Overview
+UI/UX principles are evaluative lenses for making interfaces understandable, efficient, and forgiving. The two most-cited canons are Nielsen's 10 usability heuristics (broad rules of thumb for evaluating interaction design) and the Laws of UX (psychology and cognitive-science principles applied to design). Read this when designing a new flow, doing a heuristic review, or justifying a design decision.
+
+## Official sources
+- Nielsen Norman Group — 10 Usability Heuristics: https://www.nngroup.com/articles/ten-usability-heuristics/
+- Laws of UX: https://lawsofux.com/
+
+## Core concepts
+- **Visibility of system status** — the design keeps users informed about what is happening through timely, appropriate feedback (NN/g heuristic #1).
+- **Match between system and the real world** — speak the users' language with familiar words and concepts rather than internal jargon (NN/g #2).
+- **User control and freedom** — provide clear "emergency exits" (undo/cancel) so users can leave unwanted states (NN/g #3).
+- **Consistency and standards** — users should not have to wonder whether different words or actions mean the same thing; follow platform conventions (NN/g #4).
+- **Recognition rather than recall** — minimize memory load by making elements, actions, and options visible (NN/g #6).
+- **Aesthetic and minimalist design** — keep only relevant content so it does not compete with the essential (NN/g #8).
+- **Laws of UX** — psychology-based principles such as Jakob's Law (users prefer familiar patterns), Hick's Law (more choices increase decision time), Fitts's Law (target acquisition depends on size and distance), and the Aesthetic-Usability Effect (per lawsofux.com).
+
+## Best practices
+- Run a heuristic evaluation against NN/g's 10 heuristics before usability testing; they catch a large share of problems cheaply (NN/g).
+- Prevent errors rather than only reporting them — the best designs stop problems before they occur (NN/g heuristic #5).
+- Apply Hick's Law: reduce or group choices to speed decisions, and stage complex tasks progressively (lawsofux.com).
+- Lean on Jakob's Law: reuse established conventions so users transfer existing mental models instead of learning yours (lawsofux.com).
+
+## Common pitfalls
+- Treating heuristics as rigid pass/fail checks → use them as discussion prompts to surface issues, weighting severity by frequency and impact (NN/g).
+- Hiding system state (no loading or success feedback) → always signal status within a reasonable time (NN/g heuristic #1).
+- Overloading a screen to look "complete" → remove non-essential content; clutter reduces relative visibility of what matters (NN/g heuristic #8).
+- Inventing novel interaction patterns for common tasks → favor familiar conventions (Jakob's Law) unless a measured benefit justifies the learning cost.
+
+## Examples
+```text
+Heuristic review checklist (excerpt):
+[ ] #1 Status: is progress/loading/success visibly communicated?
+[ ] #3 Control: can the user undo or cancel every destructive action?
+[ ] #5 Prevention: are invalid inputs blocked before submission?
+[ ] #6 Recognition: are key options visible rather than memorized?
+```
+
+## Further reading
+- NN/g full heuristic articles (one deep-dive per heuristic): https://www.nngroup.com/articles/ten-usability-heuristics/
+- Laws of UX individual law pages: https://lawsofux.com/
+
+## Related skills
+- ../microinteractions — feedback and state cues that realize "visibility of system status"
+- ../design-systems — encoding consistency and standards as reusable components