Skip to content

CLAUDE.md

Latest commit

 

History

History
156 lines (127 loc) · 7.22 KB

CLAUDE.md

File metadata and controls

156 lines (127 loc) · 7.22 KB

DS Prototype Template

Lightweight Vue 3 app for building static prototypes using the Ankorstore Design System.

Stack

  • Vue 3 + TypeScript + Vite 8 (Rolldown)
  • @ankorstore/design-system v28 (component library)
  • Vue Router (page navigation)
  • CSS design tokens (src/styles/design-tokens.css)
  • Static JSON fixtures (mock data)

Commands

  • npm run dev — Start dev server (http://localhost:3000)
  • npm run build — Type-check + build for static deployment
  • npm run preview — Preview production build
  • npm run upgrade-ds — Update @ankorstore/design-system to latest
  • npm run deploy — Build and deploy to GitHub Pages (pushes dist/ to gh-pages branch)

File Conventions

  • Pages: src/pages/ — one .vue file per page
  • Mock data: src/data/ — JSON files + TypeScript interfaces in types.ts
  • Layout: src/layouts/ — AppLayout wraps all pages (sidebar + topbar)
  • Components: src/components/ — reusable page-level components
  • Routes: src/router.ts — add new routes here when creating pages
  • Styles: src/styles/design-tokens.css — CSS custom properties for spacing, typography, radius
  • Directory rules: src/components/CLAUDE.md, src/pages/CLAUDE.md

Creating a New Page

  1. Create src/pages/MyPage.vue:
<template>
  <div style="padding: var(--space-5); display: flex; flex-direction: column; gap: var(--space-5);">
    <h2>My Page Title</h2>
    <!-- Your content using DS components -->
  </div>
</template>

<script setup lang="ts">
// Use Composition API with script setup
</script>
  1. Add route in src/router.ts:
{ path: '/my-page', component: () => import('@/pages/MyPage.vue'), meta: { title: 'My Page' } }
  1. Add nav link in src/components/AppSidebar.vue → navItems array:
{ path: '/my-page', label: 'My Page', icon: 'grid' }
  1. (Optional) Create fixture data in src/data/my-data.json + add interface in types.ts

Component Rules (CRITICAL)

  • ONLY use components from @ankorstore/design-system (prefixed with Ak*)
  • Do NOT install other UI libraries (no Vuetify, PrimeVue, etc.)
  • Do NOT use raw HTML elements when a DS component exists:
    • Use <AkButton> not <button>
    • Use <AkInput> not <input>
    • Use <AkAlert> not custom alert divs
    • Use <AkTable> not <table>
  • Use CSS custom properties from design-tokens.css: var(--space-4), var(--radius-md)
  • Layout utility classes available: .flex, .flex-col, .gap-4, .items-center, etc.
  • In <style scoped>: use plain CSS with CSS custom properties
  • Components are globally registered — no imports needed in templates

Most-Used Components (Quick Reference)

Component Key Props Event
<AkButton> color="primary" size="md" outlined symbol="plus" loading @onClick
<AkInput> v-model label type placeholder iconLeft @input
<AkSelect> v-model :options="[{label,value}]" placeholder @change
<AkTable> :columns :data :border :rowStyles="['hover']" @rowClick
<AkBadge> content color="green" size="sm" symbol —

AkTable columns: { name: string, label: string, width?: string, align?: 'left'|'center'|'right' } AkTable custom cells: #item.[columnName]="{ item }" — Custom headers: #column.[columnName]

Full API for all 18+ components: See src/llms-component-catalog.md

Common Recipes

Data Table with Filters

See src/pages/OrderListPage.vue — combines AkTable + AkInput + AkSelect + AkPagination + AkBadge

Card Layout with Data Display

See src/pages/OrderDetailPage.vue — card grid with definition lists

Form Layout

<div style="display: flex; flex-direction: column; gap: var(--space-4); max-width: 500px;">
  <AkInput v-model="name" label="Name" placeholder="Enter name..." required />
  <AkInput v-model="email" label="Email" type="email" placeholder="you@example.com" />
  <AkSelect v-model="role" :options="roleOptions" label="Role" />
  <AkButton color="primary" @onClick="submit">Save</AkButton>
</div>

Confirmation Modal

<AkButton @onClick="$refs.confirmModal.openModal()">Delete</AkButton>
<AkModal ref="confirmModal" size="sm" titleContent="Confirm Delete" validateButtonText="Delete" validateButtonColor="error" cancelButtonText="Cancel" @validated="onDelete">
  <p>This action cannot be undone.</p>
</AkModal>

Status Badge Mapping

const statusColors: Record<string, string> = {
  pending: 'orange', confirmed: 'blue', shipped: 'purple', delivered: 'green', cancelled: 'red'
}
<AkBadge :content="status" :color="statusColors[status]" size="sm" />

Empty State

<AkAlert type="info" title="No results">Try adjusting your filters.</AkAlert>

Working with Data

  • Import JSON: import orders from '@/data/orders.json'
  • TypeScript types: import type { Order } from '@/data/types'
  • Create new fixture: add .json in src/data/, add interface in types.ts
  • Use computed() for filtering: const filtered = computed(() => data.filter(...))
  • Do NOT fetch from APIs — all data is static JSON

Styling Guide

  • Design tokens in src/styles/design-tokens.css — use var(--space-4), var(--radius-md), etc.
  • Colors come from DS (loaded via design-system.css): primary=#14060A, neutral-100=#F9F9F9, neutral-200=#F0F0F0, neutral-700=#808080, neutral-900=#4D4D4D, error-700=#DE043C, success-700=#557566, info-700=#0B00F4
  • Layout utility classes available: .flex, .flex-col, .gap-4, .items-center, etc.
  • In <style scoped>: use plain CSS with CSS custom properties
  • Font: Poppins (loaded via Google Fonts)
  • Responsive breakpoints: xs(480), sm(640), md(768), lg(1024), xl(1280), 2xl(1600)
  • Prefer DS component props over custom CSS

AI Agent Support

  • Vite 8 console forwarding: server.forwardConsole is enabled — browser console.log, console.warn, console.error, and unhandled errors are forwarded to the terminal during npm run dev. AI agents can see runtime Vue warnings and JS exceptions without browser access.
  • Playwright MCP: Configured in .mcp.json (project-scoped, shared via git). Enables AI agents to take screenshots, click through pages, test responsive layouts, and verify component rendering. Start dev server first (npm run dev), then use Playwright tools to interact with http://localhost:3000.

Gotchas

  • SPA routing on GitHub Pages: Vue Router uses createWebHistory — GitHub Pages doesn't handle client-side routing natively. Deep links (e.g., /orders/123) will 404 without a custom 404.html redirect. Dev server handles this fine.
  • Deploy: Run npm run deploy to build and push to gh-pages branch. Set GitHub Pages source to "Deploy from branch" → gh-pages / / (root) in repo settings.
  • AkModal ref pattern: Open modals via this.$refs.modal.openModal() (Options API) or template ref + .value.openModal() (Composition API)
  • DS component events: AkButton uses @onClick (not @click), AkSelect uses @change, AkTable uses @rowClick

Entry Points

index.html → src/main.ts → App.vue → AppLayout.vue (sidebar + topbar) → <router-view />

Full Component Catalog

See src/llms-component-catalog.md for complete component documentation with all props, slots, and events.