Toge Component Builder

Sub-components live in a subfolder: src/toge/primitives/stepper/step/step.vue

Which Tier?

Tier 1 — Primitives (src/toge/primitives/): ONE indivisible visual element Tier 2 — Molecules (src/toge/molecules/): 2–3 atoms forming a new named UI concept Tier 3 — Patterns (src/toge/patterns/): layout shell with product-injected slots

4-Question Test for Primitives:

1. Does it render ONE thing?
2. Can it exist without knowing WHY?
3. Only props + slots as input?
4. Can two different products use it unchanged? → All YES = Primitive. Any NO = Molecule or Pattern.

Molecule vs Pattern:

• Self-contained visual concept (chip, banner, datepicker) → Molecule
• Layout shell with named slots for product content → Pattern

One-Way Rule: primitives → tokens only molecules → primitives + sibling molecules patterns → molecules + primitives ❌ Never import upward (patterns → molecules is OK, molecules → patterns is NOT)

TypeScript Conventions

Emits interface syntax:

// ✅ Correct — tuple syntax
export interface ButtonEmits {
  'click': [event: MouseEvent]
  'update:modelValue': [value: string]
}

// ❌ Wrong — function syntax
export interface ButtonEmits {
  click: (event: MouseEvent) => void
}

Style Conventions

// {name}.styles.ts — pure function, zero Vue imports
import classNames from 'classnames'

export interface ButtonStyleProps {
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

export function getButtonClasses(p: ButtonStyleProps) {
  return {
    base: classNames('spr-flex spr-items-center spr-gap-2', {
      'spr-opacity-50 spr-cursor-not-allowed': p.disabled,
    }),
    label: classNames('spr-body-md-semibold'),
  }
}

Critical rules:

• ALL Tailwind classes use spr- prefix — spr-flex, spr-w-full, spr-gap-2 etc.
• Zero Vue imports in .styles.ts — it must be a pure JS/TS module
• Import classNames from classnames

Vue Component Rules

<script lang="ts" setup>
import { computed } from 'vue'
import { Icon } from '@iconify/vue'           // icons
import { Menu } from 'floating-vue'           // dropdowns
import classNames from 'classnames'           // ad-hoc classes if needed
import { getButtonClasses } from './button.styles'
import type { ButtonProps, ButtonEmits, ButtonSlots } from './button.types'

const props = withDefaults(defineProps<ButtonProps>(), {
  variant: 'primary',
  disabled: false,
})
const emit = defineEmits<ButtonEmits>()
defineSlots<ButtonSlots>()

const model = defineModel<string>({ default: '' })  // only if v-model needed
const classes = computed(() => getButtonClasses(props))
</script>

Icon imports: Always import { Icon } from '@iconify/vue' — never other icon libs.

Dropdown overlays: Always import { Menu } from 'floating-vue' with <template #reference> + <template #popper>.

No dayjs — use native Date math for date calculations.

Justified vs. Unjustified State

Rule: If the product should own it, strip it. Emit an event instead.

What to Strip When Migrating from v1

v1 components live in src/components/. When migrating to toge:

1. Strip @vueuse/core — replace useVModel → defineModel, onClickOutside → floating-vue auto-hide
2. Strip textField/valueField normalization — accept pre-shaped SelectOption[]
3. Strip disabledLocalSearch — all search is external, just emit search
4. Strip createPinia() — snackbar anti-pattern; accept snacks prop instead
5. Strip getMonthList/getYearList emits — date pickers shouldn't fetch data
6. Strip localStorage — table drag-drop reordering goes away entirely
7. Keep floating-vue <Menu> — it's a peer dep, use it for all popover overlays

Naming Conventions

Parallel Agent Strategy

For 3+ independent components, dispatch parallel agents:

Group 1: foundational (list + dropdown)
Group 2: form variants (select + select-multiple + select-ladderized)
Group 3: filter UI (filter + attribute-filter)
Group 4: table ecosystem (table + table-actions + table-pagination + sub-cells)
Group 5: date ecosystem (date-calendar-picker + date-picker + date-range + month-year)
Group 6: special cases (snackbar)

After agents complete: Wire lib/toge.ts and playground yourself — do not delegate this.

lib/toge.ts Wiring

After all components in a phase are built:

// Primitive:
export { default as TogeButton } from '../src/toge/primitives/button/button.vue'
// Molecule:
export { default as TogeAvatar } from '../src/toge/molecules/avatar/avatar.vue'
// Pattern:
export { default as TogeAccordion } from '../src/toge/patterns/accordion/accordion.vue'

// Type re-exports
export type * from '../src/toge/primitives/button/button.types'

// Utility exports (if any)
export { generateTimeSlots } from '../src/toge/molecules/time-picker/time-picker.styles'

// Store exports (special cases only)
export { useSnackbarStore } from '../src/toge/stores/useSnackbarStore'

Known gotcha: defineProps defaults cannot reference locally declared variables (Vue SFC limitation). Inline the value directly in the default factory.

// ❌ Build error
const DEFAULT_OPTIONS = [10, 20, 50]
withDefaults(defineProps<Props>(), { options: () => DEFAULT_OPTIONS })

// ✅ Works
withDefaults(defineProps<Props>(), { options: () => [10, 20, 50] })

Playground Registration

After wiring lib/toge.ts, add to src/playground/TogePlayground.vue:

Import:

// Primitive:
import TogeButton from '@/toge/primitives/button/button.vue'
// Molecule:
import TogeAvatar from '@/toge/molecules/avatar/avatar.vue'
// Pattern:
import TogeAccordion from '@/toge/patterns/accordion/accordion.vue'

Registry entry (ComponentConfig interface):

{
  component: TogeButton,       // Component reference
  tag: 'toge-button',          // kebab-case tag for code gen
  propDefs: [...],             // Configurable props
  defaultSlot?: 'Click me',    // If component has a default slot
  extraProps?: { ... },        // Pre-populated data (items, options, headers)
  hasModel?: true,             // If component uses defineModel
  modelDefault?: '',           // Initial modelValue
}

Special preview cases (add v-else-if in template):

• collapsible — needs named #trigger slot
• tooltip — needs trigger element
• popper — needs #content slot
• dropdown — needs #reference slot
• snackbar — teleports to body, show explanation note

Data-heavy components use extraProps for sample data:

extraProps: {
  items: [{ text: 'Option A', value: 'a' }, ...],
  headers: [{ name: 'Name', field: 'name', sort: true }, ...],
  tableData: [{ name: 'John Doe', ... }, ...],
}

Build Verification

Always run after wiring:

npm run build:toge

Expected output: ✓ built in X.XXs with no errors. Fix any errors before declaring phase complete.

Check diagnostics:

• IDE diagnostics on TogePlayground.vue must be zero
• IDE diagnostics on all new component files must be zero

Floating-Vue Clipping Pattern

Any toge component that uses <Menu> from floating-vue must follow this pattern.

The DOM floating-vue generates:

.v-popper__wrapper
  .v-popper__inner          ← floating-vue owns this: sets border-radius:6px, bg, border, shadow
    <anonymous div>         ← floating-vue slot wrapper
      <div class="...">     ← our classes.menu div (from .styles.ts)
        <slot />

The rule:

1. Visual ownership lives in .styles.ts — border, bg, shadow, border-radius on classes.menu using design tokens. Never hardcode these in raw CSS.
2. .v-popper__inner must be neutralized via a <style> block scoped with popper-class. Reset its border, bg, shadow to none. Set overflow: hidden.
3. border-radius on .v-popper__inner MUST match our inner div's radius — if it's smaller, overflow:hidden clips our rounded corners at the wrong shape.
4. Use popper-class="toge-{name}-popper" on <Menu> to scope the CSS override without leaking to other floating-vue instances.

Template pattern:

<Menu popper-class="toge-popover-popper" ...>
  <template #default><slot name="reference" /></template>
  <template #popper>
    <div :class="classes.menu">  <!-- owns all visual styling -->
      <slot />
    </div>
  </template>
</Menu>

Style block pattern (popover.vue):

<style>
/* Neutralize floating-vue's .v-popper__inner — our classes.menu div owns the visual.
   border-radius MUST match the token used in classes.menu (e.g. border-radius-lg = --size-250).
   If they differ, overflow:hidden clips our rounded corners at the wrong shape. */
.toge-popover-popper .v-popper__inner {
  border-radius: var(--size-250) !important; /* sync with classes.menu radius */
  overflow: hidden !important;
  border: none !important;
  box-shadow: none !important;
  padding: 0 !important;
}
</style>

See reference implementation: src/toge/primitives/popover/popover.vue + popover.styles.ts

Border-Radius Nesting Rule (R2 = R1 + D)

When a container wraps rounded inner content with padding, the outer radius should equal the inner radius plus the gap:

R2 (outer container) = R1 (inner content radius) + D (padding between them)

Design token values:

Example (popover + list): list item R1=8px (border-radius-md) + popover padding D=8px (p-2) → popover R2 should be 16px (border-radius-xl). User may choose the nearest token that looks right visually.

Common Mistakes

Phase Reference

Self-Update Protocol

After every successful toge task, review this skill:

1. Did we discover a new pattern or convention? Add it to the relevant section.
2. Did we hit a new gotcha? Add to Common Mistakes.
3. Did a new component type need special handling? Document the approach.
4. Update the Phase Reference table if a new phase completes.

Update this file at: ~/.claude/skills/toge-component-builder/SKILL.md Also sync to: skill/toge-component-builder/SKILL.md (project-local copy)