@meistrari/tela-build 1.33.0 → 1.34.0

package/components/tela/button/button.mdx

@@ -7,6 +7,28 @@ import * as ButtonStories from './button.stories.ts';
 
 A versatile button component with multiple variants, sizes, and states. Supports icons, loading states, and can function as a link when provided with a `to` prop. Built for consistent UI interactions across the application.
 
+## Rules
+
+- **Never** use `variant="ghost"` — use `secondary` instead.
+- **Never** use `size="sm"` — always `md` (default) or `lg`.
+- Since `md` is the default, omit the `size` prop unless you need `lg`.
+- When a `TelaButton` sits beside a `TelaInput` in the same row, both must use `size="md"` (default). Never mix sizes in the same row — it creates misaligned rows.
+- **Icon API — two separate props, never one.** The icon **name** goes on `icon`; its **position** is toggled with the boolean `leading`. Default position is trailing. `leading` never takes a value.
+
+```vue
+<!-- ✅ Correct — icon on the leading side -->
+<TelaButton icon="i-ph-export" leading>Export</TelaButton>
+
+<!-- ✅ Correct — icon on the trailing side (default) -->
+<TelaButton icon="i-ph-arrow-right">Next</TelaButton>
+
+<!-- ❌ Wrong — `leading` is a boolean, not a slot for the icon name -->
+<TelaButton leading="i-ph-export">Export</TelaButton>
+
+<!-- ❌ Wrong — no `icon` prop means no icon renders -->
+<TelaButton leading>Export</TelaButton>
+```
+
 ## Examples
 
 ### All Sizes

package/components/tela/card/card.mdx

@@ -2,6 +2,14 @@
 
 A surface container component used to group related content with consistent visual boundaries.
 
+## Rules
+
+- **Always** use the `size` prop to control card padding and radius — do not use `content-padding` or `border-radius` props.
+- Attributify spacing/radius props (`p-*`, `px-*`, `py-*`, `rounded-*`) are intentionally ignored on `<TelaCard>` to keep `size` deterministic. If you need a forced override, use `class` with the important modifier (e.g. `class="!p-0"`).
+- Cards in grids must use `h-full` for consistent heights.
+- **Never** wrap `TelaTable` in `TelaCard` — tables are their own surface.
+- Small gaps look like accidents next to large typography. Use at least `gap-4px` when a card contains a large typographic element — prefer `gap-6px` when the large text is the primary content.
+
 ## Size Prop
 
 Always use the `size` prop to control card padding — it maps directly to the standardized values. Never apply padding manually to `<TelaCard>` or its inner elements.
@@ -45,12 +53,34 @@ Always use the `size` prop to control card padding — it maps directly to the s
 
 ### Card Grid
 
+Cards in grids must use `h-full` for consistent heights.
+
 ```vue
 <div class="grid grid-cols-3 gap-4">
-  <TelaCard v-for="item in items" :key="item.id">...</TelaCard>
+  <TelaCard v-for="item in items" :key="item.id" h-full>...</TelaCard>
 </div>
 ```
 
+### Gap with Large Text
+
+```vue
+<!-- Wrong — too tight -->
+<TelaCard size="sm">
+  <div flex flex-col gap-1>
+    <span body-12-medium text-secondary>Total Requests</span>
+    <span heading-h2-semibold text-primary>128,430</span>
+  </div>
+</TelaCard>
+
+<!-- Correct -->
+<TelaCard size="sm" h-full>
+  <div flex flex-col gap-4px>
+    <span body-12-medium text-secondary>Total Requests</span>
+    <h1 heading-h1-semibold text-primary>128,430</h1>
+  </div>
+</TelaCard>
+```
+
 ## Props
 
 | Prop | Type | Default | Description |

package/components/tela/card/card.vue

@@ -13,12 +13,11 @@ const props = withDefaults(defineProps<{
 })
 
 const sizeStyles = computed(() => (({
-    sm: { padding: 'p-24px', rounded: 'rounded-12px' },
-    md: { padding: 'p-32px sm:p-48px', rounded: 'rounded-24px' },
-}) as Record<string, { padding: string, rounded: string }>)[props.size ?? 'md'] ?? { padding: '', rounded: '' })
+    sm: { padding: 'p-24px' },
+    md: { padding: 'p-32px' },
+}) as Record<string, { padding: string }>)[props.size ?? 'md'] ?? { padding: '' })
 
 const paddingClass = computed(() => props.contentPadding ?? sizeStyles.value.padding)
-const borderRadiusClass = computed(() => props.borderRadius ?? sizeStyles.value.rounded)
 const rootEl = ref<HTMLElement | null>(null)
 
 defineExpose({
@@ -27,7 +26,7 @@ defineExpose({
 </script>
 
 <template>
-    <div ref="rootEl" :class="cn('bg border-0.5px border', paddingClass, borderRadiusClass, props.class)">
+    <div ref="rootEl" :class="cn('rounded-16px bg border-0.5px border', paddingClass, props.class)">
         <slot />
     </div>
 </template>

package/components/tela/dropdown-menu/dropdown-menu.mdx

@@ -7,6 +7,23 @@ import * as DropdownMenuStories from './dropdown-menu.stories.ts';
 
 A dropdown menu component built on radix-vue. Provides a flexible menu system with support for grouping, icons, tooltips, checkboxes, and search functionality. Items can be organized into groups and can include click handlers, disabled states, and custom styling.
 
+## Rules
+
+- **Always** include an `icon` on every item. Icons give each action a visual identity and make the menu scannable.
+
+### DropdownMenu vs SelectMenu
+
+Use `TelaDropdownMenu` when clicking triggers a side effect. Use `TelaSelectMenu` when the action updates a bound value.
+
+| Scenario | Component |
+|---|---|
+| Export, duplicate, archive, configure | `TelaDropdownMenu` |
+| Navigation links and actions | `TelaDropdownMenu` |
+| Choose environment, select status, pick a model | `TelaSelectMenu` |
+| Filtering or form field with options | `TelaSelectMenu` |
+
+**The test:** If clicking triggers a side effect → `TelaDropdownMenu`. If it updates a bound value → `TelaSelectMenu`.
+
 ## Examples
 
 ### Basic Usage

package/components/tela/header/header.mdx

@@ -7,6 +7,16 @@ import * as HeaderStories from './header.stories.ts';
 
 A composable header component for fullscreen views. Provides a sticky top bar with three layout zones: leading (left), center, and trailing (right). Built with slot-based sub-components for maximum flexibility.
 
+## Rules
+
+- **Always** use `TelaHeader` on details pages (single resource, editor, settings) — never build page chrome from scratch.
+- For root pages (index, list, dashboard) use `TelaSidebar` instead.
+
+| Page type | Shell |
+|---|---|
+| Details page (single resource, editor, settings) | `TelaHeader` |
+| Root page (index, list, dashboard) | `TelaSidebar` |
+
 ## Examples
 
 ### Basic Usage

package/components/tela/icon-button/icon-button.mdx

@@ -0,0 +1,94 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Inputs/IconButton" />
+
+# TelaIconButton
+
+An icon-only button for compact actions (toolbars, modal close buttons, inline controls). Supports multiple sizes, colors, loading, and disabled states, and can render as a link when `to` is provided.
+
+## Rules
+
+- **Never** use `color="primary"` — always `color="secondary"`.
+- The default is `primary`, so **always set `color` explicitly**.
+
+## Examples
+
+### Basic Usage
+
+```vue
+<TelaIconButton
+  icon="i-ph-gear"
+  color="secondary"
+/>
+```
+
+### As a Close Button (inside Modal)
+
+```vue
+<TelaIconButton
+  icon="i-ph-x"
+  size="md"
+  color="secondary"
+  outline-none
+  p-8px mt--12px mr--16px
+  @click="isOpen = false"
+/>
+```
+
+### As a Link
+
+```vue
+<TelaIconButton
+  icon="i-ph-arrow-up-right"
+  color="secondary"
+  to="https://example.com"
+  target="_blank"
+/>
+```
+
+### Loading State
+
+```vue
+<TelaIconButton
+  icon="i-ph-gear"
+  color="secondary"
+  loading
+/>
+```
+
+## Props
+
+```typescript
+type IconButtonSize = '3xs' | '2xs' | 'xs' | 'sm' | 'md'
+type IconButtonColor = 'primary' | 'secondary'
+
+type IconButtonProps = {
+  color?: IconButtonColor
+  icon: string
+  size?: IconButtonSize
+  outline?: boolean
+  disabled?: boolean
+  loading?: boolean
+  active?: boolean
+  iconClass?: string
+  buttonClass?: string
+  to?: string
+  target?: '_blank' | null
+}
+```
+
+## Events
+
+- `longpress` — emitted after a 700ms press-and-hold (ignored when `disabled`).
+
+## Features
+
+- **Compact**: Icon-only surface for dense layouts.
+- **Link Functionality**: Renders as `NuxtLink` when `to` is provided.
+- **Long-press**: Built-in long-press detection.
+- **States**: `disabled`, `loading`, `active`, `outline`.
+
+## Accessibility
+
+- Renders as a `<button>` (or `<NuxtLink>` when `to` is set).
+- Always pair with a visible label or tooltip so the action is discoverable by screen readers.

package/components/tela/input/input.mdx

@@ -7,6 +7,24 @@ import * as InputStories from './input.stories.ts';
 
 A flexible input component that supports both text input and textarea modes. Includes features like labels, error states, icons, clear buttons, and validation feedback. Supports v-model binding for two-way data binding.
 
+## Rules
+
+- **Always** use `size="md"` (default). When a `TelaInput` sits next to a `TelaButton` in the same row, both must be `md` — never mix sizes, it creates misaligned rows.
+- Inside a `TelaModal`, the input must be `w-full`.
+
+### Search
+
+Search fields **never** have a submit button. Use an inline `TelaInput` that filters as the user types.
+
+```vue
+<!-- Correct -->
+<TelaInput v-model="query" placeholder="Search..." hide-label />
+
+<!-- Wrong — no submit button next to a search input -->
+<TelaInput v-model="query" placeholder="Search..." hide-label />
+<TelaButton>Search</TelaButton>
+```
+
 ## Examples
 
 ### With Clear Button

package/components/tela/modal/modal.mdx

@@ -6,6 +6,77 @@ import { Meta, ArgTypes } from '@storybook/blocks';
 
 A modal dialog component that displays content in a centered overlay. Useful for important messages, confirmations, forms, and content that requires user attention.
 
+`TelaDialog` is deprecated — **always** use `TelaModal`.
+
+## Rules
+
+- **Never** pass `title` to `TelaModal` — build the header yourself inside the slot.
+- **Always** set `:compact="true"` and `:hide-dividers="true"`.
+- **Always** set `:is-close-icon="false"` — build the close button manually with `TelaIconButton`.
+- Close button negative margins must equal **half the modal padding** → `mt--{p/2} mr--{p/2}`.
+- Footer layout: `flex justify-end gap-8px`.
+- Every control inside a modal must fill the modal width. See [Width](#width) below.
+
+### Recommended Structure
+
+```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 — negative margins = half the modal padding -->
+      <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>
+```
+
+### Width
+
+Every control inside a modal must fill the modal width. `w-full` on the root of a compound component (`TelaSelectMenu`, `TelaCombobox`) does not reach the trigger — use `trigger-class="w-full"` instead.
+
+```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 />
+```
+
 ## Props
 
 <ArgTypes />

package/components/tela/select-menu/select-menu.mdx

@@ -7,6 +7,36 @@ import * as SelectMenuStories from './select-menu.stories.ts';
 
 A flexible select menu component built on reka-ui. Allows users to select a single option from a dropdown list. Supports icons, descriptions, tooltips, grouping, and custom styling.
 
+## Rules
+
+- **Never** place icons before text in select options.
+- **Always** set `trigger-class` to constrain the trigger width — never let it overflow or expand the layout.
+
+| Context | Value |
+|---|---|
+| Inside modals and forms | `trigger-class="w-full"` |
+| In toolbars | `trigger-class="w-160px"` (or a fixed width) |
+
+### SelectMenu vs DropdownMenu
+
+Use `TelaSelectMenu` when the action updates a bound value. Use `TelaDropdownMenu` when clicking triggers a side effect.
+
+| Scenario | Component |
+|---|---|
+| Choose environment, select status, pick a model | `TelaSelectMenu` |
+| Filtering or form field with options | `TelaSelectMenu` |
+| Export, duplicate, archive, configure | `TelaDropdownMenu` |
+| Navigation links and actions | `TelaDropdownMenu` |
+
+**The test:** If clicking updates a bound value → `TelaSelectMenu`. If it triggers a side effect → `TelaDropdownMenu`.
+
+### Filters
+
+When building a filter panel, always use `TelaSelectMenu` for options with multiple choices — never toggles or checkboxes. Filter panels must include **Apply / Clear** actions and must never auto-apply on change:
+
+- Apply: default primary `TelaButton`
+- Clear: `variant="secondary"` `TelaButton`
+
 ## Examples
 
 ### Basic Usage

package/components/tela/sidebar/sidebar.mdx

@@ -7,6 +7,38 @@ import * as SidebarStories from './sidebar.stories.ts';
 
 A composable sidebar navigation system built from focused sub-components. Fixed 80px wide and full-height, designed for icon-based navigation with labels.
 
+## Rules
+
+- **Always** use `TelaSidebar` on root pages (index, list, dashboard) — never hand-roll a sidebar, `<nav>`, or custom rail.
+- For details pages (single resource, editor, settings) use `TelaHeader` instead — the sidebar is not part of a details surface.
+- **Always position the sidebar as `sticky`** (`sticky top-0 h-screen`). It must stay pinned to the viewport as the main content scrolls — never allow it to scroll away with the page.
+
+| Page type | Shell |
+|---|---|
+| Root page (index, list, dashboard) | `TelaSidebar` |
+| Details page (single resource, editor, settings) | `TelaHeader` |
+
+### Layout
+
+Place the sidebar and main content in a flex row. The sidebar is `sticky`; the `<main>` takes the remaining width with its own `max-width` + `mx-auto`.
+
+```vue
+<div flex>
+    <TelaSidebar sticky top-0 h-screen>
+        ...
+    </TelaSidebar>
+
+    <main flex="~ col" w-full max-w-1380px mx-auto px-48px py-32px>
+        <!-- page content -->
+    </main>
+</div>
+```
+
+**Never:**
+- Let the sidebar scroll with the page (missing `sticky`)
+- Use `h-screen` / `h-[calc(...)]` height hacks on the page wrapper — flex + the sticky sidebar handle sizing
+- Replace `<main>` with a plain `<div>` — semantics matter
+
 ## Examples
 
 ### Full Sidebar

package/components/tela/status/status.mdx

@@ -7,6 +7,11 @@ import * as StatusStories from './status.stories.ts';
 
 A status component that displays different workflow and task statuses with appropriate icons, colors, and labels. Supports multiple status types including pending, running, completed, error, and review states. Features smooth animations and automatic width transitions for a polished user experience.
 
+## Rules
+
+- **Always** use `<TelaStatus />` for any status indicator (workflow status, event status, health state, etc.). Never build a custom status with icons + color classes.
+- `text-success` and `text-error` are reserved for `<TelaStatus />` — never apply them to regular text content.
+
 ## Examples
 
 ### Default Status

package/components/tela/table/table-cell.vue

@@ -10,7 +10,7 @@ const props = defineProps<{
     <td
         :class="
             cn(
-                'p-4 align-middle [&:has([role=checkbox])]:pr-0',
+                'p-4 body-14-regular text-primary align-middle [&:has([role=checkbox])]:pr-0',
                 props.class,
             )
         "

package/components/tela/table/table.mdx

@@ -206,6 +206,10 @@ The Table system consists of these components:
 - `TelaTableCaption` - Accessible table description (`<caption>`)
 - `TelaTableEmpty` - Empty state component for when no data is available
 
+## Rules
+
+- **Never use `items-end` + `text-right` on cells**, except when styling the last column. Right-alignment is reserved for the trailing column (typically numeric totals or actions); applying it to middle columns breaks visual scan order and column alignment.
+
 ## Features
 
 - **Responsive**: Horizontal scrolling on smaller screens

package/lib/doc-generator.ts

@@ -566,8 +566,55 @@ export function generateDocsToDirectory(componentDocs: ComponentDoc[], typeResol
     const body = dedent`
 # Tela Build
 
-This Skill provides structured documentation for the Tela Build component library (Vue 3 + Nuxt).
-Use it when building, refactoring, or using Tela components — props, events, slots, and examples are included where available.
+UI library and design engineering principles for building polished interfaces.
+Always consult before making UI changes. Use when building UI components, reviewing frontend code, or polishing visual details — animations, hover states, shadows, borders, typography, micro-interactions,
+spacing, border radius, optical alignment. Triggers on UI polish, "feels off", design details.
+
+## Objective
+
+**Tela Build skill exists to produce pixel-perfect UI.** Every output — new component, review, or polish pass — must be measured against that bar. "Close enough" is not acceptable. Concentric border radius, optical alignment, intentional gaps, exact tokens, clean negative space, precise typography — all of it must be correct, not approximate. If a detail is off by a pixel or a token is wrong, it is not done.
+
+## Instructions
+
+- IMPORTANT: Before making ANY UI change or introducing NEW UI, ALWAYS consult this Tela Build components index first.
+- Prefer reusing existing Tela components and patterns. Only create new components when a clear gap exists.
+- When a new component is needed, align with existing naming, props, events, and patterns documented here.
+- Keep this documentation current when components are added or changed (update supporting files under \
+  \`components/\`).
+
+## Quick Reference
+
+| Category | When to use |
+|---|---|
+| Tokens | Choosing colors, text styles, backgrounds, borders, or icon colors |
+| Interfaces | Layout decisions, component rules, spacing, styling patterns, do/don'ts |
+| Surfaces | Border radius, depth strategy, elevation, outlines, hit areas |
+| Typography | Heading tokens, body font sizes, font weights |
+| Animations | Deciding when to animate, easing, duration, springs, and staggered enter animations |
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Same border radius on parent and child | Calculate \`outerRadius = innerRadius + padding\` |
+| Icons look off-center | Adjust optically with padding or fix SVG directly |
+| \`transition: all\` on elements | Specify exact properties |
+| First-frame animation stutter | Add \`will-change: transform\` (sparingly) |
+
+## Review Output Format
+
+Always present changes as a markdown table with Before and After columns. Include every change you made — not just a subset. Never list findings as separate "Before:" / "After:" lines outside of a table. Group changes by principle using a heading above each table, and keep each row focused on a single diff so the reader can scan the whole list quickly.
+
+## Review Checklist
+
+- [ ] Nested rounded elements use concentric border radius
+- [ ] Before building, scan the Components Index and reuse existing components — never hand-roll UI when a component exists
+- [ ] Double-check negative space, gaps, and padding — squint at the layout and confirm it reads as clean and intentional, not cramped or accidental
+- [ ] Typography follows the rules — semantic \`heading-*\` and \`body-*\` tokens only (no raw \`text-Xpx\`/\`font-*\`), the right token for each level (h1 page title, h2 section, h3/h4 subsection, body-14 supporting), and a mix of regular/medium/semibold weights so hierarchy isn't flat
+- [ ] Icons are optically centered, not just geometrically
+- [ ] Headings use text-wrap: balance
+- [ ] No \`transition: all\` — only specific properties
+- [ ] \`will-change\` only on transform/opacity/filter, never \`all\`
 
 ## Components Index
 

package/lib/tela-build-skill.ts

@@ -1,8 +1,4 @@
 export const telaBuildSkill = {
     name: 'tela-build',
-    description: [
-        'Use when working on any UI in this repository. Ask for component props, slots, variants, and usage examples.',
-        'Always consult this Tela Build index BEFORE making any UI changes or creating new UI.',
-        'Use it for components, layouts, styling, interactions, and design-token decisions.',
-    ].join('\n'),
+    description: 'Use when working on any UI in this repository. Ask for component props, slots, variants, and usage examples. Always consult this Tela Build index BEFORE making any UI changes or creating new UI. Use it for components, layouts, styling, interactions, and design-token decisions.',
 } as const

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-build",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "type": "module",
   "files": [
     "app.config.ts",