@meistrari/tela-build 1.50.0 → 1.50.1

package/docs/animations.md

@@ -0,0 +1,161 @@
+# Animations
+
+Principles for deciding when to animate, choosing easing and duration, using springs, and building staggered enter animations.
+
+Before writing any animation code, answer these questions in order:
+
+### 1. Should this animate at all?
+
+**Ask:** How often will users see this animation?
+
+| Frequency                                                   | Decision                     |
+| ----------------------------------------------------------- | ---------------------------- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever.          |
+| Tens of times/day (hover effects, list navigation)          | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts)                        | Standard animation           |
+| Rare/first-time (onboarding, feedback forms, celebrations)  | Can add delight              |
+
+**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow, delayed, and disconnected from the user's actions.
+
+Raycast has no open/close animation. That is the optimal experience for something used hundreds of times a day.
+
+### 2. What is the purpose?
+
+Every animation must have a clear answer to "why does this animate?"
+
+Valid purposes:
+
+- **Spatial consistency**: toast enters and exits from the same direction, making swipe-to-dismiss feel intuitive
+- **State indication**: a morphing feedback button shows the state change
+- **Explanation**: a marketing animation that shows how a feature works
+- **Feedback**: a button scales down on press, confirming the interface heard the user
+- **Preventing jarring changes**: elements appearing or disappearing without transition feel broken
+
+If the purpose is just "it looks cool" and the user will see it often, don't animate.
+
+### 3. What easing should it use?
+
+Is the element entering or exiting?
+  Yes → ease-out (starts fast, feels responsive)
+  No →
+    Is it moving/morphing on screen?
+      Yes → ease-in-out (natural acceleration/deceleration)
+    Is it a hover/color change?
+      Yes → ease
+    Is it constant motion (marquee, progress bar)?
+      Yes → linear
+    Default → ease-out
+
+**Critical: use custom easing curves.** The built-in CSS easings are too weak. They lack the punch that makes animations feel intentional.
+
+**Never use ease-in for UI animations.** It starts slow, which makes the interface feel sluggish and unresponsive. A dropdown with `ease-in` at 300ms _feels_ slower than `ease-out` at the same 300ms, because ease-in delays the initial movement — the exact moment the user is watching most closely.
+
+**Easing curve resources:** Don't create curves from scratch. Use [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) to find stronger custom variants of standard easings.
+
+### 4. How fast should it be?
+
+| Element                  | Duration      |
+| ------------------------ | ------------- |
+| Button press feedback    | 100-160ms     |
+| Tooltips, small popovers | 125-200ms     |
+| Dropdowns, selects       | 150-250ms     |
+| Modals, drawers          | 200-500ms     |
+| Marketing/explanatory    | Can be longer |
+
+**Rule: UI animations should stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. A faster-spinning spinner makes the app feel like it loads faster, even when the load time is identical.
+
+### Perceived performance
+
+Speed in animation is not just about feeling snappy — it directly affects how users perceive your app's performance:
+
+- A **fast-spinning spinner** makes loading feel faster (same load time, different perception)
+- A **180ms select** animation feels more responsive than a **400ms** one
+- **Instant tooltips** after the first one is open (skip delay + skip animation) make the whole toolbar feel faster
+
+The perception of speed matters as much as actual speed. Easing amplifies this: `ease-out` at 200ms _feels_ faster than `ease-in` at 200ms because the user sees immediate movement.
+
+## Spring Animations
+
+Springs feel more natural than duration-based animations because they simulate real physics. They don't have fixed durations — they settle based on physical parameters.
+
+### When to use springs
+
+- Drag interactions with momentum
+- Elements that should feel "alive" (like Apple's Dynamic Island)
+- Gestures that can be interrupted mid-animation
+- Decorative mouse-tracking interactions
+
+This works because the animation is **decorative** — it doesn't serve a function. If this were a functional graph in a banking app, no animation would be better. Know when decoration helps and when it hinders.
+
+### Spring configuration
+
+**Apple's approach (recommended — easier to reason about):**
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+```
+
+**Traditional physics (more control):**
+
+```js
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Keep bounce subtle (0.1-0.3) when used. Avoid bounce in most UI contexts. Use it for drag-to-dismiss and playful interactions.
+
+## Enter Animations: Split and Stagger
+
+Don't animate a single large container. Break content into semantic chunks and animate each individually.
+
+### Step by Step
+
+1. **Split** into logical groups (title, description, buttons)
+2. **Stagger** with ~100ms delay between groups
+3. **For titles**, consider splitting into individual words with ~80ms stagger
+4. **Combine** `opacity`, `blur`, and `translateY` for the enter effect
+
+### Code Example
+
+```vue
+<script setup lang="ts">
+const itemVariants = {
+    hidden: { opacity: 0, y: 12, filter: 'blur(4px)' },
+    visible: { opacity: 1, y: 0, filter: 'blur(0px)' },
+}
+</script>
+
+<template>
+    <Motion
+        initial="hidden"
+        animate="visible"
+        :variants="{ visible: { transition: { staggerChildren: 0.1 } } }"
+    >
+        <Motion as="h1" :variants="itemVariants">
+            Welcome
+        </Motion>
+
+        <Motion as="p" :variants="itemVariants">
+            A description of the page.
+        </Motion>
+
+        <Motion :variants="itemVariants">
+            <TelaButton>Get started</TelaButton>
+        </Motion>
+    </Motion>
+</template>
+```
+
+### When It Breaks
+
+Don't use `initial={false}` when the component relies on its `initial` prop to set up a first-time enter animation, like a staggered page hero or a loading state. In those cases, removing the initial animation skips the entire entrance.
+
+```vue
+// Bad — initial={false} would skip the staggered page enter entirely
+<AnimatePresence initial={false}>
+    <Motion initial="hidden" animate="visible" :variants="{...}">
+        ...
+    </Motion>
+</AnimatePresence>
+```
+
+Verify the component still looks right on a full page refresh before applying this.

package/docs/interfaces.md

@@ -0,0 +1,457 @@
+# Interfaces
+
+Build with craft and consistency. Every decision is a design decision.
+
+This document has two halves:
+
+1. **Philosophy** — how to think about an interface _before_ you write it.
+2. **Tela Design System** — the concrete rules for building interfaces in this codebase.
+
+If you're here to look up a component rule, skip to [Tela Design System](#tela-design-system). If you're starting a new surface from scratch, read from the top.
+
+---
+
+# Part 1 — Philosophy
+
+## Intent First
+
+Before writing a single line of code, answer these out loud.
+
+| Question                | Bad answer          | Good answer                                                             |
+| ----------------------- | ------------------- | ----------------------------------------------------------------------- |
+| **Who is this human?**  | "Users"             | A teacher at 7am. A founder between calls. A dev debugging at midnight. |
+| **What must they do?**  | "Use the dashboard" | Grade submissions. Find the broken deploy. Approve the payment.         |
+| **How should it feel?** | "Clean and modern"  | Warm like a notebook. Cold like a terminal. Dense like a trading floor. |
+
+If you can't answer with specifics — stop. Ask. Do not guess. Do not default.
+
+### Every Choice Must Be Intentional
+
+For every decision, explain **why**: layout, color temperature, typeface, spacing scale, information hierarchy.
+
+**The swap test:** If you replaced your choices with the most common alternatives and nothing felt meaningfully different — you defaulted, not designed.
+
+### Intent Must Be Systemic
+
+Stating "warm" and using cold colors is a failure. Intent is a constraint that shapes _everything_.
+
+- **Warm** → surfaces, text, borders, accents, typography — all warm
+- **Dense** → spacing, type size, information architecture — all dense
+- **Calm** → motion, contrast, color saturation — all calm
+
+## Where Defaults Hide
+
+Defaults disguise themselves as infrastructure — the parts that "just need to work."
+
+**Typography** feels like a container. But it _is_ your design. A bakery tool and a trading terminal both need "readable type" — but warm and handmade is not cold and precise. If you're reaching for your usual font, you're not designing.
+
+**Navigation** feels like scaffolding. But navigation _is_ your product. Where you are, where you can go, what matters most. A floating page is a component demo, not software.
+
+**Data** feels like presentation. But a number on screen is not design. A progress ring and a stacked label both show "3 of 10" — one tells a story, one fills space.
+
+**Token names** feel like implementation. But `--ink` and `--parchment` evoke a world. `--gray-700` evokes a template. Your tokens should hint at the product.
+
+> The moment you stop asking "why this?" is the moment defaults take over.
+
+## Product Domain Exploration
+
+Generic process: `Task type → Visual template → Theme`
+Crafted process: `Task type → Product domain → Signature → Structure + Expression`
+
+Before proposing any direction, produce all three:
+
+| Output        | Description                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| **Domain**    | Concepts, metaphors, vocabulary from this product's world. Not features — territory. Minimum 5.      |
+| **Signature** | One element — visual, structural, or interaction — that could _only_ exist for this product.         |
+| **Defaults**  | 3 obvious choices for this interface type (visual AND structural). Name them so you can reject them. |
+
+Your direction must reference domain concepts, your signature element, and what replaces each default.
+
+**The identity test:** Remove the product name from your proposal. Can someone identify what it's for? If not — it's generic.
+
+### Worked example — a workflow run detail page
+
+Bad (generic): "Tabs across the top for Overview, Logs, Variables. Status pill in the corner. Metric cards above the fold."
+
+Good:
+
+```
+Domain:    dag · step · run · trigger · input/output contract · retry · branch · checkpoint
+Signature: the run is a timeline of steps — each step's input and output are always visible on
+           the same row, so the contract between steps reads as naturally as the execution does.
+Rejecting: tabs (fragments context)          → single scrollable timeline
+           status pill in a corner           → status inline with each step row
+           metric cards above the fold       → summary synthesized from the timeline itself
+```
+
+Every direction the agent then proposes — typography, spacing, card shape, motion — must serve that timeline-with-visible-contracts signature. If it doesn't, it's a default in disguise.
+
+## Craft Foundations
+
+Every pattern has infinite expressions. **No interface should look the same.**
+
+A metric display could be: hero number, inline stat, sparkline, gauge, progress bar, delta, trend badge — or something new.
+
+Before building a surface, ask:
+
+1. What's the ONE thing users do most here?
+2. What products solve similar problems brilliantly? Study them.
+3. Why would this interface feel designed for its purpose — not templated?
+
+## Checkpoint — before a surface leaves your hands
+
+You do not need to state intent before every `<div>`. You _do_ need to state it once per surface (a page, a modal, a large component) — and once before you ship it.
+
+**When you start the surface, write this in a comment or PR description:**
+
+```
+Intent:    [who is this human, what must they do, how should it feel]
+Depth:     [borders / shadows / layered — and WHY this fits the intent]
+Surfaces:  [your elevation scale — and WHY this fits the intent]
+Typography:[your typeface — and WHY it fits the intent]
+Spacing:   [your base unit]
+```
+
+If you can't explain **why** for each choice — you're defaulting.
+
+**Before showing the surface to the user**, ask: _"If they said this lacks craft, what would they mean?"_ That thing you just thought of — **fix it first.** Then run the four checks:
+
+| Check              | Question                                                                                                          |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| **Swap test**      | If you swapped the typeface or layout for the most common alternative — would anyone notice?                      |
+| **Squint test**    | Blur your eyes. Is hierarchy still perceptible? Anything jumping harshly?                                         |
+| **Signature test** | Can you point to five specific elements where your signature appears? Not "the overall feel" — actual components. |
+| **Token test**     | Read your CSS variables out loud. Do they sound like this product's world, or any project?                        |
+
+If any check fails — iterate before showing.
+
+## Design Principles
+
+### Spacing
+
+Pick a base unit. Use only multiples.
+
+| Context                  | Use                |
+| ------------------------ | ------------------ |
+| Icon gaps, tight inline  | micro (4px)        |
+| Within buttons and cards | component (8–12px) |
+| Between groups           | section (16–24px)  |
+| Between distinct areas   | major (32px+)      |
+
+### Other Principles
+
+**Layout width** — Don't cap page containers with an arbitrary `max-w-*`. A number like `max-w-1280px` is almost always a habit, not a decision — it shrinks the canvas for no stated reason and fights the app shell that already constrains width. Let content, grid, and surrounding layout determine width. If you do cap, state what breaks without the cap (line length for prose, column count for dense tables) and pick the value from that constraint.
+
+**Padding** — Keep it symmetrical. Asymmetry only when content demands it.
+
+**Border radius** — Sharper = technical. Rounder = friendly. Build a scale: small for inputs/buttons, medium for cards, large for modals. Don't mix randomly.
+
+**Cards** — A metric card doesn't have to look like a plan card. Design each card's internal structure for its content. Keep surface treatment consistent: same border weight, shadow depth, corner radius, padding scale.
+
+**Controls** — Native `<select>` and `<input type="date">` can't be styled. Always build custom components.
+
+**Icons** — Icons clarify, not decorate. If removing an icon loses no meaning — remove it. One icon set. Give standalone icons a subtle background container.
+
+**Animation** — Fast micro-interactions, smooth easing. Use deceleration. Avoid bounce in professional interfaces.
+
+**States** — Every interactive element needs: default, hover, active, focus, disabled. Every data state: loading, empty, error.
+
+**Navigation** — Screens need grounding. A floating data table is a component demo. Include where you are in the app, location indicators, user context.
+
+---
+
+# Part 2 — Tela Design System
+
+## Components
+
+### Page Shell
+
+Every page mounts inside the same shell. Never rebuild it.
+
+- Need a sidebar? **Use `TelaSidebar`.** Never hand-roll a sidebar, `<nav>`, or custom rail.
+- Need a header? **Use `TelaHeader`.** Never build page chrome from scratch.
+
+| Page type                                        | Shell         |
+| ------------------------------------------------ | ------------- |
+| Root page (index, list, dashboard)               | `TelaSidebar` |
+| Details page (single resource, editor, settings) | `TelaHeader`  |
+
+Root pages get the sidebar for navigation and context. Details pages get the header for location (back action, title, primary action) — the sidebar is not part of a details surface.
+
+### Layouts
+
+Before building a new page from scratch, check for an existing **layout template** and use it if one fits. Layouts package the entire page structure — scroll model, header, columns, footer — so surfaces stay consistent and you don't re-assemble (or re-debug) that scaffolding by hand.
+
+| Layout | Use for | Docs |
+| --- | --- | --- |
+| `TelaHome` (`home.vue`) | Root index / list / dashboard pages with a sidebar rail. | `components/tela/home/home.mdx` |
+| `TelaDetails` (`details.vue`) | Full-screen detail / record pages and fullscreen modals. | `components/tela/details/details.mdx` |
+
+**`TelaHome`** — a flex-row shell: a sticky `TelaSidebar` beside a scrolling `TelaHomeContent` column that stacks a page title, a metric-card row (`TelaHomeMetrics`), a filter toolbar (`TelaHomeToolbar`), and a data table. It does **not** own scroll — the sidebar pins itself (`sticky top-0 h-screen`) and the page scrolls as one, no `overflow` container or height hack. Expandable detail rows are an opt-in enhancement.
+
+**`TelaDetails`** — a sticky `TelaHeader` + a single scroll container + a primary content column beside a sticky context column, with an optional confirm footer. Two documented variants — a two-column body, and a hero header above the body.
+
+This table is the source of truth for layout templates. Rules:
+
+- If a layout fits the surface, use it. Don't hand-roll an equivalent.
+- If none fits, fall back to the [Page Shell](#page-shell) primitives (`TelaSidebar` / `TelaHeader`) — don't invent a new full-page structure inline.
+- When you build a new reusable layout, document it and add a row here so it becomes a discoverable template.
+
+### Button
+
+- **Never** use `variant="ghost"` on `TelaButton` — use `secondary` instead
+- **Never** use `size="sm"` — always `md` (default) or `lg`
+- Since `md` is default, omit the `size` prop unless you need `lg`
+- Icon API: `icon="i-…"` for the name, `leading` as a boolean for position — never `leading="i-…"`
+
+### IconButton
+
+- **Never** use `color="primary"` on `TelaIconButton` — always `color="secondary"`
+- The default is `primary`, so always set it explicitly
+
+### Select
+
+- **Never** place icons before text in select options
+- **Always** set `trigger-class` to constrain width — never let the trigger overflow or expand the layout
+
+| Context                 | Value                                |
+| ----------------------- | ------------------------------------ |
+| Inside modals and forms | `trigger-class="w-full"`             |
+| In toolbars             | `trigger-class="w-160px"` (or fixed) |
+
+### Dropdown vs Select
+
+| Scenario                                        | Component          |
+| ----------------------------------------------- | ------------------ |
+| Export, duplicate, archive, configure           | `TelaDropdownMenu` |
+| Choose environment, select status, pick a model | `TelaSelectMenu`   |
+| Navigation links and actions                    | `TelaDropdownMenu` |
+| Filtering or form field with options            | `TelaSelectMenu`   |
+
+**The test:** If clicking triggers a side effect → Dropdown. If it updates a bound value → Select.
+
+**Dropdown items:** Always include an `icon` on every `TelaDropdownMenu` item. Icons give each action a visual identity and make the menu scannable.
+
+### Input & Button Heights
+
+Always use `size="md"` (default) for both `TelaInput` and `TelaButton` when they appear together. Never mix sizes in the same row — it creates misaligned rows.
+
+### Search
+
+Search fields never have a submit button. Always an inline `TelaInput` that filters as the user types.
+
+```vue
+<!-- Correct — inline filter -->
+<TelaInput v-model="query" placeholder="Search..." hide-label />
+
+<!-- Wrong — never pair search with a submit button -->
+<div flex gap-8px>
+  <TelaInput v-model="query" placeholder="Search..." hide-label />
+  <TelaButton>Search</TelaButton>
+</div>
+```
+
+### Filters
+
+Always include **Apply / Clear** action buttons in filter panels. Never auto-apply on change.
+
+- Apply: default primary `TelaButton`
+- Clear: `variant="secondary"` `TelaButton`
+- Multiple options: always `TelaSelectMenu` — never toggles or checkboxes
+
+### Status
+
+Always use `<TelaStatus />` for any status indicator. Never build custom status with icons and color classes.
+
+### Table
+
+- Never wrap `TelaTable` in `TelaCard` — tables are their own surface.
+- **ALWAYS wrap the table in `<div mx--16px>`** so cell padding doesn't indent the table content from the header / title row above it. The negative margin cancels the cell's horizontal padding, pulling the first column flush with the surrounding content. This is the default — a table that sits directly inside a padded surface and skips the wrap will look misaligned (its content nudged in from everything above it).
+
+```vue
+<div mx--16px>
+  <TelaTable>
+    <!-- ... -->
+  </TelaTable>
+</div>
+```
+
+**The one exception — interactive rows with a hanging affordance.** When rows have an trigger component that hangs into the left gutter (e.g. the expand caret on clickable/expandable rows in the [`TelaHome`](?path=/docs/layout-home--docs) example, paired with `:has-scroll-area="false"`), do **not** add `mx--16px` — the gutter padding is what gives that affordance room and keeps it from being clipped. So: **wrap plain tables every time; only skip the wrap when a hanging row affordance needs the gutter.**
+
+### Modal
+
+Always use `TelaModal`. `TelaDialog` is deprecated — never use it.
+
+```vue
+<TelaModal
+  v-model="isOpen"
+  modal-width="md"
+  :compact="true"
+  :hide-dividers="true"
+  :is-close-icon="false"
+>
+  <div flex="~ col" w-full gap-16px>
+    <!-- Header -->
+    <div flex="~ row justify-between" items-start>
+      <div flex="~ col" gap-4px>
+        <h4 heading-h4-semibold text-primary>Dialog Title</h4>
+        <p body-14-regular text-secondary>Dialog subtitle or description.</p>
+      </div>
+
+      <!-- Close Button -->
+      <TelaIconButton
+        icon="i-ph-x"
+        size="md"
+        color="secondary"
+        outline-none
+        p-8px mt--12px mr--16px
+        @click="isOpen = false"
+      />
+    </div>
+
+    <!-- Content -->
+    <div flex="~ col" gap-8px>
+      <!-- ... -->
+    </div>
+
+    <!-- Footer -->
+    <div flex gap-8px justify-end>
+      <TelaButton variant="secondary" @click="isOpen = false">Cancel</TelaButton>
+      <TelaButton>Submit</TelaButton>
+    </div>
+  </div>
+</TelaModal>
+```
+
+**Rules:**
+
+- Never pass `title` to `TelaModal` — build the header yourself inside the slot
+- Always use `:compact="true"` and `:hide-dividers="true"`
+- Always use `:is-close-icon="false"` — build the close button manually
+- Close button negative margins = **half the modal padding** → `mt--{p/2} mr--{p/2}`
+- Footer: `flex justify-end gap-8px`
+
+**Width — all controls inside a modal must fill the modal:**
+
+```vue
+<!-- Correct -->
+<TelaInput v-model="val" label="Name" w-full />
+
+<TelaTextarea v-model="val" w-full />
+
+<TelaToggleGroup v-model="val" :options="opts" w-full />
+
+<TelaSelectMenu v-model="val" :options="opts" trigger-class="w-full" />
+
+<TelaCombobox v-model="val" :options="opts" trigger-class="w-full" />
+
+<!-- Wrong — w-full on root doesn't reach the trigger -->
+<TelaSelectMenu v-model="val" :options="opts" w-full />
+
+<TelaCombobox v-model="val" :options="opts" w-full />
+```
+
+### Card
+
+| Card type                     | Prop        |
+| ----------------------------- | ----------- |
+| Large, standard, medium cards | `size="md"` |
+| Small / minor cards           | `size="sm"` |
+
+Always use the `size` prop to control card spacing and radius. Do not use `content-padding` or `border-radius` props.
+
+**Rule: use `size="md"` for large content, otherwise use `size="sm"`.** `md` is for primary surfaces — the hero card on a dashboard, a settings panel, a section that carries the page. `sm` is for minor surfaces — KPI cards, nested cards, compact side panels, anything supporting the primary surface. Defaulting everything to `md` flattens hierarchy; defaulting everything to `sm` starves the page of presence. Pick based on what the card is, not by feel.
+
+Do not pass attributify spacing/radius props (for example `p-*`, `px-*`, `py-*`, `rounded-*`) to `<TelaCard>`. Those attributes are intentionally ignored to keep `size` deterministic; if you need a forced override, use `class` with the important modifier (for example `class="!p-0"`).
+
+Cards in grids must use `h-full` for consistent heights.
+
+```vue
+<!-- Standard card -->
+<TelaCard size="md" h-full>
+  <h3>Card Title</h3>
+  <p>Card content</p>
+</TelaCard>
+
+<!-- Minor card -->
+<TelaCard size="sm">
+  <p text-secondary mb-2>Capacity</p>
+  <p heading-h2-semibold>20</p>
+</TelaCard>
+```
+
+#### Gap with Large Text
+
+Small gaps look like accidents next to large typography. Use at least `gap-12px` when a container holds a large typographic element — prefer `gap-16px` when the large text is the primary content.
+
+```vue
+<!-- Wrong — too tight -->
+<div flex flex-col gap-4px>
+  <span body-12-medium text-secondary>Total Requests</span>
+  <span heading-h2-semibold text-contrast>128,430</span>
+</div>
+
+<!-- Correct -->
+<div flex flex-col gap-12px>
+  <span body-12-medium text-secondary>Total Requests</span>
+  <span heading-h2-semibold text-contrast>128,430</span>
+</div>
+```
+
+## Styling
+
+Use direct attributes for static styles. Use `class` only for dynamic or conditional styles.
+
+```vue
+<!-- Static — direct attributes -->
+<div flex items-center gap-16px p-20px bg-muted rounded-12px>
+  <span text-primary heading-h3-semibold>Title</span>
+</div>
+
+<!-- Dynamic — use class -->
+<div :class="isActive ? 'bg-blue-600' : 'bg-muted'">
+Content
+</div>
+```
+
+Never duplicate attributes on the same element:
+
+```vue
+<!-- Wrong -->
+<div flex="~ 1" flex="~ col">
+...
+</div>
+
+<!-- Correct -->
+<div flex flex-1 flex-col>
+...
+</div>
+```
+
+## Do / Don't
+
+**Do:**
+
+- Use semantic tokens over raw color values
+- Use `0.5px` borders on all components
+- Apply `h-full` to cards in grid/list layouts
+- Use `12px` radius for `size="sm"` cards and `8px` for nested elements/badges
+- Use direct attributes for static styles
+- Use `<TelaStatus />` for all status indicators
+- Use `text-primary` or `text-secondary` for all text content
+- Use `TelaSelectMenu` for filters with multiple options
+
+**Don't:**
+
+- Use `TelaDialog` — always `TelaModal`
+- Use `class` for static styles
+- Use legacy colors (`colors.dark`, `colors.base`, `colors.caution`, `colors.negative`, `colors.black`)
+- Use border widths other than `0.5px`
+- Use arbitrary spacing, radius, or color values
+- Cap page containers with a default `max-w-*` — let content and the app shell decide width
+- Wrap `TelaTable` in `TelaCard` — tables are their own surface
+- Build custom status indicators
+- Use `text-success` or `text-error` on text — reserved for `<TelaStatus />`
+- Use standalone icons in interfaces — text and labels are always sufficient
+  - **Exception:** icons are allowed inside `<TelaButton />` via the `leading` prop

package/docs/surfaces.md

@@ -0,0 +1,127 @@
+# Surfaces
+
+Layering, elevation, depth, and borders — the invisible structure of craft.
+
+## Concentric Border Radius
+
+When nesting rounded elements, the outer radius must equal the inner radius plus the padding between them:
+
+```
+outerRadius = innerRadius + padding
+```
+
+This rule is most useful when nested surfaces are close together. If padding is larger than `24px`, treat the layers as separate surfaces and choose each radius independently instead of forcing strict concentric math.
+
+### Example
+
+```vue
+// Good — outer radius accounts for padding
+<div rounded-16px p-8px>       {/* 16px radius, 8px padding */}
+  <div rounded-8px>          {/* 8px radius = 16 - 8 ✓ */}
+    ...
+  </div>
+</div>
+
+// Bad — same radius on both
+<div rounded-16px p-8px>
+  <div rounded-16px>          {/* same radius, looks off */}
+    ...
+  </div>
+</div>
+```
+
+Mismatched border radius on nested elements is one of the most common things that makes interfaces feel off. Always calculate concentrically.
+
+## Borders
+
+Borders should disappear when you're not looking, but be findable when you need structure.
+
+- Always `0.5px` width — no exceptions
+- Use semantic tokens: `border` → `border-subtle` → `border-strong`
+- **The squint test**: Blur your eyes. Perceive hierarchy? Nothing jumping harshly? Craft whispers.
+
+## Dividers
+
+A divider is a border drawn as its own element — so it follows the same `0.5px` rule as borders.
+
+- Always `h-0.5px` for a horizontal rule, `w-0.5px` for a vertical one — **never** `h-1px` / `w-1px`. A `1px` line is twice as heavy as every border on the page and breaks the hairline rhythm.
+- Color it with a border token (`bg-border`, `bg-border-subtle`, `bg-border-strong`), not a raw gray.
+- Prefer spacing over a divider when a gap alone separates the content (see [Negative space](#negative-space-is-a-positive-choice)).
+
+```vue
+<!-- Correct -->
+<div h-0.5px w-full bg-border />
+
+<!-- Wrong — 1px (h-px / h-1px) is heavier than every border on the page -->
+<div h-px w-full bg-border />
+```
+
+## Depth — Pick One and Commit
+
+| Strategy | Character | Best for |
+|---|---|---|
+| Borders-only | Clean, technical | Dense tools |
+| Subtle shadows | Soft lift | Approachable products |
+| Layered shadows | Premium, dimensional | Cards needing presence |
+| Surface color shifts | Tint-based hierarchy | No shadows |
+
+Do not mix approaches.
+
+## Spacing, Gaps & Negative Space
+
+Spacing is not decoration — it is the language of hierarchy. A single `gap` value applied to everything flattens a layout. Related content stops reading as related; major sections stop reading as major. Before choosing a gap, ask what is equal and what is nested.
+
+### Group before you gap
+
+**Equal spacing between siblings implies equal importance.** If two rows are structurally siblings under the same `gap`, the eye reads them as peers. Two metric-card rows at the same level under `gap-40px` become two separate sections, not one metrics surface.
+
+The fix is structural, not numeric: wrap related blocks in their own container and give that container a tighter internal `gap`. Reserve the larger `gap` for genuinely distinct sections.
+
+```vue
+// Bad — hero cards and summary cards read as two unrelated sections
+<main flex="~ col" gap-40px>
+    <div>page header</div>
+    <div grid="~ cols-3">...hero cards...</div>   // 40px away from the next row
+    <div grid="~ cols-3">...summary cards...</div> // 40px away from the table
+    <div>...table...</div>
+</main>
+
+// Good — hero + summary grouped into one metrics section; 40px only between major sections
+<main flex="~ col" gap-40px>
+    <div>page header</div>
+
+    <div flex="~ col" gap-16px>                    // metrics section
+        <div grid="~ cols-3">...hero cards...</div>
+        <div grid="~ cols-3">...summary cards...</div>
+    </div>
+
+    <div>...table...</div>
+</main>
+```
+
+### Gap hierarchy
+
+Pick at least two gap values per page and use them consistently:
+
+| Level | Gap | Use for |
+|---|---|---|
+| **Major sections** | `gap-40px` | Between page header, primary content blocks, and trailing sections (e.g. header → metrics → table) |
+| **Related groups** | `gap-16px` | Between sibling surfaces inside the same section (e.g. hero row + summary strip) |
+| **Within a card** | `gap-12px` / `gap-16px` | Between label, value, and supporting text inside a card |
+| **Large + small typography** | `gap-12px` minimum, `gap-16px` preferred | Whenever a container pairs a label with a hero number or heading — never `gap-4px` or `gap-8px`, which read as accidents |
+
+If every gap on the page is the same, you have not made a hierarchy decision — you have deferred it.
+
+### Negative space is a positive choice
+
+- Empty space around a hero number is what makes it feel heavy. Do not fill silence with decoration.
+- Asymmetric padding reads as a mistake. Keep padding symmetrical unless the content demands otherwise.
+- A section break is earned by contrast — change in surface, in density, or in gap. Do not insert dividers where spacing alone would do the job.
+
+### Checklist before shipping
+
+- Can you point to at least two distinct `gap` values on the page? If not, the hierarchy is flat.
+- Are logical groups wrapped in their own container, or are they leaking into the page-level gap?
+- Squint at the layout. Do major sections separate naturally, or does everything feel like one list?
+
+If any answer is no — regroup before tweaking numbers.

package/docs/tokens.md

@@ -0,0 +1,92 @@
+# Tokens
+
+Tokens are design decisions expressed as code. If a token exists for what you need, use it. Always.
+
+## Semantic Tokens First
+
+Semantic tokens describe the role of a color, not its value. Roles survive theme changes, brand updates, and redesigns. Values don't.
+
+```vue
+<!-- Correct — semantic tokens -->
+<span text-primary>Label</span>
+<div bg-muted />
+<div border />
+
+<!-- Wrong — raw values for things tokens already cover -->
+<span class="text-gray-200">Label</span>
+<div class="bg-[#1a1a1a]" />
+```
+
+## Raw Palettes — Sparingly
+
+When no semantic token covers your use case, raw palette values are allowed. Use them as a last resort, not a shortcut.
+
+```vue
+<div bg-gray-800 />
+<div bg-blue-600 />
+```
+
+If a raw value will recur, it belongs in the token system — not scattered across components.
+
+## Legacy Colors — Never
+
+These are deprecated. If you encounter them, replace with the semantic equivalent.
+
+```typescript
+// Never use these
+colors.dark
+colors.base
+colors.caution
+colors.negative
+colors.black
+colors.gray[20] // or any numeric gray shade
+```
+
+## Token Reference
+
+### Background
+
+Surfaces stack. Use the right background token for each layer — not by feel, but by role.
+
+- **`bg`** — Base layer. App background and primary surfaces. (`DT.colors.background`)
+- **`bg-subtle`** — One level up. Secondary panels, sidebars. (`DT.colors.background.subtle`)
+- **`bg-muted`** — Inputs, cards, contained areas. (`DT.colors.background.muted`)
+- **`bg-lowered`** — Below the base. Subtle separators, recessed areas. (`DT.colors.background.lowered`)
+- **`bg-success`** — Success state backgrounds in badges and alerts. (`DT.colors.background.success`)
+- **`bg-error`** — Error state backgrounds in badges and alerts. (`DT.colors.background.error`)
+- **`bg-warning`** — Warning state backgrounds in badges and alerts. (`DT.colors.background.warning`)
+
+### Text
+
+For typography, default to `text-primary` (content) and `text-secondary` (support) — see [Typography → Color](./typography.md#color--primary-and-secondary-only). The remaining text tokens are for specific roles, not for expressing hierarchy in copy.
+
+- **`text-primary`** — Default body text. Most content. (`DT.colors.text.primary`)
+- **`text-secondary`** — Supporting text, metadata, labels. (`DT.colors.text.secondary`)
+- **`text-tertiary`** — Placeholders, disabled states — not "quieter body text". (`DT.colors.text.tertiary`)
+- **`text-subtle`** — Very low emphasis, over muted surfaces only. (`DT.colors.text.subtle`)
+- **`text-contrast`** — Reserved; primary is already the default heading color. (`DT.colors.text.contrast`)
+- **`text-icon`** — Icon color applied via text utility. (`DT.colors.text.icon`)
+- **`text-success`** — Success messaging and status indicators. (`DT.colors.text.success`)
+- **`text-error`** — Error messaging, destructive action labels. (`DT.colors.text.error`)
+- **`text-warning`** — Warning messaging, caution indicators. (`DT.colors.text.warning`)
+- **`text-pending`** — In-progress and pending state indicators. (`DT.colors.text.pending`)
+
+### Border
+
+Borders should disappear when you're not looking for them. Use the right intensity for the boundary.
+
+- **`border`** — Default. Most component borders. (`DT.colors.border`)
+- **`border-subtle`** — Quiet dividers on light surfaces. (`DT.colors.border.subtle`)
+- **`border-strong`** — Emphasized. Containers that need presence. (`DT.colors.border.strong`)
+- **`border-accent`** — High-emphasis accent borders. (`DT.colors.border.accent`)
+- **`border-inverse`** — Borders on dark/inverted surfaces. (`DT.colors.border.inverse`)
+
+### Icon
+
+Icons follow the same emphasis hierarchy as text — match the icon level to its context.
+
+- **`icon`** — Default icon color. (`DT.colors.icon`)
+- **`icon-secondary`** — Supporting icons, slightly de-emphasized. (`DT.colors.icon.secondary`)
+- **`icon-tertiary`** — Low-emphasis icons, metadata level. (`DT.colors.icon.tertiary`)
+- **`icon-subtle`** — Disabled or de-emphasized icons. (`DT.colors.icon.subtle`)
+- **`icon-inverse`** — Icons on dark/inverted surfaces. (`DT.colors.icon.inverse`)

package/docs/typography.md

@@ -0,0 +1,35 @@
+# Typography
+
+Typography tweaks for a more polished UI.
+
+## Heading Tokens
+
+Each heading level has three weight variants. Pick based on what the content needs to communicate, not habit.
+
+## Headings
+
+| Token                 | Usage            |
+| --------------------- | ---------------- |
+| `heading-h1-semibold` | Page title       |
+| `heading-h2-semibold` | Section          |
+| `heading-h3-semibold` | Subsection       |
+| `heading-h4-semibold` | Minor heading    |
+| `heading-h5-semibold` | Small heading    |
+| `heading-h6-semibold` | Smallest heading |
+
+## Body
+
+| Token                                | Usage                                 |
+| ------------------------------------ | ------------------------------------- |
+| `body-20-regular` / `body-20-medium` | Long-form, pairs with `h1`            |
+| `body-16-regular` / `body-16-medium` | Primary body, pairs with `h2`         |
+| `body-14-regular` / `body-14-medium` | Supporting text, pairs with `h3`/`h4` |
+| `body-12-regular` / `body-12-medium` | Captions, labels, metadata            |
+
+## Weights
+
+- **Regular (400)** — body text
+- **Medium (460)** — labels, emphasis
+- **Semibold (580)** — headings, key actions
+
+Use all three. If you only use regular and semibold, the hierarchy is flat.

package/lib/__tests__/doc-generator.test.ts

@@ -1,11 +1,13 @@
-import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join } from 'pathe'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'pathe'
 import matter from 'gray-matter'
 import { afterEach, describe, expect, it } from 'vitest'
 import { generateDocsToDirectory } from '../doc-generator'
 import { TypeResolver } from '../type-resolver'
 
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
 const tempDirs: string[] = []
 
 afterEach(() => {
@@ -30,4 +32,26 @@ describe('generateDocsToDirectory', () => {
         })
         expect(skillMd).toContain('description: "')
     })
+
+    it('appends package docs to the tela-build skill', () => {
+        const outDir = mkdtempSync(join(tmpdir(), 'tela-build-docs-'))
+        const layerPath = mkdtempSync(join(tmpdir(), 'tela-build-layer-'))
+        tempDirs.push(outDir, layerPath)
+
+        mkdirSync(join(layerPath, 'docs'), { recursive: true })
+        writeFileSync(join(layerPath, 'docs/interfaces.md'), '# Interfaces\n\nInterface guidance.', 'utf-8')
+
+        generateDocsToDirectory([], new TypeResolver(outDir), outDir, layerPath)
+
+        const skillMd = readFileSync(join(outDir, 'tela-build', 'SKILL.md'), 'utf-8')
+
+        expect(skillMd).toContain('# Interfaces')
+        expect(skillMd).toContain('Interface guidance.')
+    })
+
+    it('ships package docs used by generated skills', () => {
+        const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'))
+
+        expect(packageJson.files).toContain('docs')
+    })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-build",
-  "version": "1.50.0",
+  "version": "1.50.1",
   "type": "module",
   "files": [
     "app.config.ts",
@@ -8,6 +8,7 @@
     "components.json",
     "composables",
     "css",
+    "docs",
     "lib",
     "modules",
     "nuxt.config.ts",