---
name: layout-spec
description: Expand compact layout/typography shorthand to Tailwind classes. Use when the user says /layout-spec. TRIGGER when: a prompt, task description, or message contains `![` followed by comma-separated shorthand (e.g. `![fs-18,fw-bold,mb-20]`).
argument-hint: "<shorthand> (comma-separated, e.g. fs-18,fw-medium,mb-20)"
---

# layout-spec — Compact Layout/Typography Shorthand

Expand compact shorthand notation into Tailwind utility classes.

## Argument syntax

```
/layout-spec <shorthand>
```

- `<shorthand>` — comma-separated `<prefix>-<value>` pairs, or a string containing `![...]` inline markers.

## Steps

### 0 — Detect mode

- **CLI mode** — the user explicitly typed `/layout-spec`. `$ARGUMENTS` contains the shorthand. Go to Step 1.
- **Trigger mode** — the skill fired because `![...]` markers appeared in a prompt or task description. Go to Step 1-T.

### 1 — Expand (CLI mode)

Run the expansion library with `$ARGUMENTS`:

```bash
result=$(./.claude/skills/layout-spec/lib/expand.sh "$ARGUMENTS")
```

If the command exits with a non-zero status, show the error message to the user and stop.

If the command emits `WARNING:` lines on stderr, show them to the user alongside the result.

### 2 — Report (CLI mode)

Show the expanded class string:

```
<shorthand> → <expanded>
```

If warnings were emitted, show them below the result. **Stop here.**

### 1-T — Expand inline markers (Trigger mode)

For each `![...]` marker found in the prompt or task description, run:

```bash
./.claude/skills/layout-spec/lib/expand.sh "<contents inside brackets>"
```

Replace the `![...]` marker with the expanded Tailwind classes in your working copy of the prompt. If expansion fails, show the error and stop.

### 2-T — Continue with the original task

The `![...]` markers are now resolved to Tailwind classes. **Continue executing the rest of the prompt/task as if the expanded classes had been written there originally.** Do not stop — the expansion was a preprocessing step, not the task itself.

---

## Shorthand reference

### Typography

| Shorthand | Expands to | Notes |
|---|---|---|
| `fs-N` | `text-N` | N must exist in `tokens.css` |
| `fs-BP-N` | `BP:text-N` | Responsive variant |
| `fw-NAME` | `font-NAME` | Output prefix is config-driven (`font-` or `fw-`) |
| `lh-N` | `leading-MAPPED` | Via config map; falls back to `leading-[N]` with warning |

### Spacing (passthrough)

| Shorthand | Expands to |
|---|---|
| `mb-20` | `mb-20` |
| `pt-40` | `pt-40` |
| `mb-lg-80` | `lg:mb-80` |
| `gap-gutter` | `gap-gutter` |
| `gap-x-md-20` | `md:gap-x-20` |

### Color (passthrough)

| Shorthand | Expands to |
|---|---|
| `text-orange` | `text-orange` |
| `bg-pink` | `bg-pink` |
| `bg-lg-gray-100` | `lg:bg-gray-100` |

### Inline form

Wrap shorthand in `![...]` inside any class string:

```html
<div class="![fs-18,fw-medium,mb-20] flex items-center">
→ <div class="text-18 font-medium mb-20 flex items-center">
```

### Breakpoints

`sm`, `md`, `lg`, `xl` — placed as the second segment: `mb-lg-80` → `lg:mb-80`.

### Validation

- Missing font size token → **hard error** (entire input rejected)
- Missing line-height mapping → **soft fallback** to arbitrary value with warning
- Unknown breakpoint or prefix → **hard error**

## Config

Auto-created on first run at `.claude/skills/layout-spec/config.json` by scanning `src/css/tokens.css`. Edit to:

- Switch font-weight prefix (`font-` → `fw-`)
- Add/override line-height mappings
- Define custom prefixes or passthrough entries
- Point to a different tokens file

## Examples

```
/layout-spec fs-18,fw-medium,mb-20
→ text-18 font-medium mb-20

/layout-spec fs-18,fs-md-22,fw-medium,lh-1.4,mb-20,mb-lg-40
→ text-18 md:text-22 font-medium leading-normal mb-20 lg:mb-40

/layout-spec mb-40,mb-lg-80,pt-md-10
→ mb-40 lg:mb-80 md:pt-10
```