markdown-ticket: Skill for Claude Code

MDT Frontend Developer

Project-specific conventions for writing frontend code in src/. Generic React/TypeScript knowledge is assumed — this skill only covers MDT-specific rules that break builds or create inconsistency.

Mandatory reads

Before touching CSS or a modal component, read these files:

1. src/STYLING.md — CSS rules: BEM naming, inline-vs-extract decision tree, surface contract
2. src/THEME.md — token reference (colors, spacing, radius, gap, typography, z-index)
3. src/PRIMITIVES.md — shared CSS class inventory (what already exists; check before inventing)
4. src/ITCSS.md — ITCSS layer architecture, nesting contract, token-gap registry
5. src/MODALS.md — three modal patterns, spacing standard, close button rules

Critical rules

1. Tailwind 3 @apply cannot chain custom classes

This is the #1 build breaker. Tailwind 3 cannot resolve custom classes (defined in @layer components) inside @apply within the same layer.

/* ❌ BREAKS BUILD — .btn is a custom class in @layer components */
.btn-primary {
  @apply btn bg-primary text-primary-foreground;
}

/* ✅ CORRECT — inline the base utilities */
.btn-primary {
  @apply inline-flex items-center justify-center rounded-md text-sm font-medium
    bg-primary text-primary-foreground;
  border: 1px solid oklch(var(--border));
}

Only Tailwind utility classes work in @apply. If you need to "extend" a base class, copy the utilities and add your own.

2. Use tokens — never invent sizes, colors, spacing, or radii

Tokens are the single source of truth. Before writing any hardcoded value (8px, 0.5rem, #hex, oklch(0.5 …)), check src/THEME.md for an existing token. If a token exists, use it. If you need a value that doesn't exist as a token, add the token to src/styles/design-tokens.css (both :root and .dark) — don't hardcode it where you need it.

Concern	Token scale (consume via bare var())	Examples
Spacing / gap	--gap-xs (4px), --gap-sm (8px), --gap-md (16px default), --gap-lg (24px)	gap: var(--gap-md); between header elements
Border radius	--radius-input (8px), --radius-card (8px), --radius-xs (4px), --radius-pill (999px)	border-radius: var(--radius-input);
Card density	--pad-y, --pad-x, --fs-xs, --fs-md (driven by CardDensity pref)	driven by useCardDensity — don't hardcode card padding
Icon / control sizing	--sz-icon (16px glyph), --sz-control (32px hit target)	glyph beside ticket key
Colors	--bg-subtle/muted/elevated, --text-muted/subtle, --primary-text, --border-strong, status/priority/type tokens	background: var(--bg-elevated);
Border	oklch(var(--border)) (shadcn channel set)	border-color: oklch(var(--border));