create-wervt 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/index.js +50 -2
  2. package/package.json +1 -1
  3. package/template/.claude/skills/nuxt-ui/SKILL.md +334 -0
  4. package/template/.claude/skills/nuxt-ui/references/components.md +377 -0
  5. package/template/.claude/skills/nuxt-ui/references/composables.md +127 -0
  6. package/template/.claude/skills/nuxt-ui/references/layouts/chat.md +195 -0
  7. package/template/.claude/skills/nuxt-ui/references/layouts/dashboard.md +220 -0
  8. package/template/.claude/skills/nuxt-ui/references/layouts/docs.md +141 -0
  9. package/template/.claude/skills/nuxt-ui/references/layouts/editor.md +167 -0
  10. package/template/.claude/skills/nuxt-ui/references/layouts/page.md +260 -0
  11. package/template/.claude/skills/nuxt-ui/references/theming.md +427 -0
  12. package/template/.claude/skills/nuxt-ui-mobile/SKILL.md +92 -0
  13. package/template/.claude/skills/nuxt-ui-mobile/examples/app/composables/useDemoItems.ts +18 -0
  14. package/template/.claude/skills/nuxt-ui-mobile/examples/app/pages/index.vue +121 -0
  15. package/template/.claude/skills/nuxt-ui-mobile/examples/app/pages/items/[id].vue +77 -0
  16. package/template/.claude/skills/nuxt-ui-mobile/examples/app/pages/settings/index.vue +71 -0
  17. package/template/.claude/skills/nuxt-ui-mobile/examples/app/pages/settings/sort.vue +23 -0
  18. package/template/.claude/skills/nuxt-ui-mobile/references/patterns.md +212 -0
  19. package/template/.claude/skills/nuxt-ui-mobile/references/review-checklist.md +49 -0
  20. package/template/.claude/skills/nuxt-ui-mobile/references/tokens.md +86 -0
  21. package/template/.claude/skills/nuxt-ui-mobile/scripts/gen-palette.mjs +58 -0
  22. package/template/.claude/skills/nuxt-ui-mobile/template/app/app.config.ts +298 -0
  23. package/template/.claude/skills/nuxt-ui-mobile/template/app/app.vue +8 -0
  24. package/template/.claude/skills/nuxt-ui-mobile/template/app/assets/css/main.css +331 -0
  25. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ActionSheet.vue +47 -0
  26. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListRow.vue +73 -0
  27. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/ListSection.vue +26 -0
  28. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/NavBar.vue +88 -0
  29. package/template/.claude/skills/nuxt-ui-mobile/template/app/components/mobile/TabBar.vue +45 -0
  30. package/template/.claude/skills/nuxt-ui-mobile/template/app/layouts/default.vue +16 -0
  31. package/template/.claude/skills/nuxt-ui-mobile/template/app/layouts/plain.vue +6 -0
  32. package/template/.claude/skills/nuxt-ui-mobile/template/nuxt.config.ts +27 -0
  33. package/template/AGENTS.md +26 -5
  34. package/template/_gitignore +2 -0
  35. package/template/package.json +2 -2
  36. package/template/pnpm-workspace.yaml +6 -0
  37. package/template/vite.config.ts +3 -1
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: nuxt-ui-mobile
3
+ description: Opinionated phone-first setup and design rules for Nuxt UI v4 apps, combining Apple's Human Interface Guidelines with Nuxt UI components. Ships a drop-in config (iOS type scale, system colors, 44pt controls, safe areas, Liquid-Glass-style bars) and mobile components (TabBar, NavBar with large title, inset grouped lists, action sheet). Use whenever building, restyling or reviewing a Nuxt/Vue + Nuxt UI app, PWA or page that is used mainly on phones or should feel like a native iOS app.
4
+ ---
5
+
6
+ # Nuxt UI Mobile
7
+
8
+ Apple's HIG mapped onto Nuxt UI. Use the config and components in `template/`, follow the rules below and check the result against `references/review-checklist.md`.
9
+
10
+ Companion skills (load when needed, not by default):
11
+ - **nuxt-ui**: component APIs, props, slots, theming mechanics. Use the Nuxt UI MCP (`get-component`) for exact props.
12
+ - **apple-hig**: the full HIG corpus. Go there for anything this skill doesn't cover, e.g. `references/hig/<topic>.md` for sheets, menus, search fields or accessibility.
13
+ - **ios-web-polish**: iOS Safari details such as cookie eviction, Web Share save-to-Photos, pull-to-refresh, long-press, pinch gestures and PWA icons.
14
+
15
+ ## Setup (new app or retrofit)
16
+
17
+ 1. Copy `template/` into the project. These files merge, they don't replace:
18
+ - `app/assets/css/main.css`: iOS text styles, system color palettes, surface tokens (`bg-grouped`, `bg-cell`, `bg-fill`), `glass`, `touch-target`, `pt-safe`/`pb-safe`.
19
+ - `app/app.config.ts`: Nuxt UI re-tuned so the default `md` size is a 44pt control with 17pt text. Also sets capsule buttons, 16px+ inputs, the iOS switch, the segmented control, bottom sheets and Phosphor icons.
20
+ - `app/components/mobile/*`: `MobileTabBar`, `MobileNavBar`, `MobileListSection`, `MobileListRow`, `MobileActionSheet`.
21
+ - `app/layouts/default.vue` (tab bar) and `plain.vue` (full-screen flows), plus `app/app.vue` (toasts at the top).
22
+ - `nuxt.config.ts`: `viewport-fit=cover`, scheme-aware `theme-color`, `ui.fonts: false`.
23
+ 2. Add the icon set with `vp add @iconify-json/ph` (or `pnpm add`). Phosphor has regular and `-fill` weights, which gives the outline-to-filled switch iOS uses for selected tabs.
24
+ 3. If the project already has a brand color, swap `primary` in `app.config.ts`. To create a palette from a hex value, see `references/tokens.md`.
25
+ 4. Look at `examples/app/pages/` for complete screens: list with search and segmented control, detail, settings, an option picker, and a form sheet.
26
+
27
+ ## Core rules
28
+
29
+ These rules are deliberately opinionated. Break one only when the user asks for it.
30
+
31
+ ### Structure and navigation
32
+ - **One column on phones.** Never use a hamburger menu or sidebar. Put 2–5 top-level sections in `MobileTabBar`. With more than 5, make one tab a list of the rest.
33
+ - **Tabs navigate, they never act.** Actions belong in the nav bar's trailing slot or inside the content.
34
+ - **Drill-down means a new route.** Use `MobileNavBar back` with a chevron-only Back button. The tab bar stays visible.
35
+ - **Nav bar buttons sit on glass**: `MobileNavBar` wraps the leading and trailing slots in shared glass capsules (iOS 26). Put only `UButton color="neutral" variant="ghost"` in them.
36
+ - **Top-level screens get a large title** (`MobileNavBar large`). It collapses into the bar on scroll. Pushed screens use the inline title. Titles should be short (under about 15 characters) and never the app name.
37
+ - **Scoped tasks (create, edit, compose) open in a sheet:** a bottom `UDrawer` with Cancel on the left, the title in the middle and the primary action (Add, Done, Save) on the right. Disable the primary action until the input is valid. Long multi-step flows get their own route with the `plain` layout.
38
+ - **Only one sheet at a time.** Never stack modals.
39
+ - **Choices about an action the person started go in an action sheet** (`MobileActionSheet` via `useOverlay`). Destructive choices are red, and Cancel is always last.
40
+ - **Alerts (`UModal`) are only for rare, irreversible, critical moments.** Use at most 2–3 buttons. The title says what will happen, buttons are verbs, and the cancel button is labeled exactly "Cancel". Never show an alert at launch, never for information only, and never for something that can be undone.
41
+ - **Undoable destructive actions run immediately.** Show a toast with an Undo action instead of asking first.
42
+ - **Menus:** an "…" `UDropdownMenu` in the nav bar is fine for secondary actions. Every item must also be reachable some other way. Use at most about 3 groups, with destructive items last.
43
+
44
+ ### Layout
45
+ - 16px side margin (`px-4` / `mx-4`). Content extends behind bars, and every edge respects safe areas. The template handles the bars and sheets. Pages need `min-h-dvh`, never `100vh`.
46
+ - **Inset grouped lists** (`MobileListSection` + `MobileListRow`) for settings, forms, metadata and short collections. Separators are inset to where the text starts. Rows are at least 44pt.
47
+ - **Chevron = drill-down only.** Action rows (`@click`) use tinted text and no chevron. Destructive rows use red text and sit in their own section at the bottom.
48
+ - **Thumb zone:** the primary action of a screen sits in the lower half or in the nav bar's trailing slot. Never put a destructive action next to a frequent one.
49
+ - **Hit areas at least 44×44.** The `touch-target` utility, already on every `UButton`, enlarges small icon buttons without changing their visual size.
50
+ - **Limit what's on screen.** Secondary actions go in "…" menus or long-press menus.
51
+ - No nested scroll areas that scroll in the same direction. Horizontal carousels inside vertical scrolling are fine; show part of the next item.
52
+
53
+ ### Type
54
+ - Use only the system font stack and the iOS text styles: `text-large-title`, `text-title-1/2/3`, `text-headline`, `text-body` (17px, the default), `text-callout`, `text-subhead`, `text-footnote`, `text-caption-1/2`. Never `text-xs`/`text-sm`/`text-2xl` or arbitrary sizes.
55
+ - Nothing smaller than 11px. No thin or light weights. Build hierarchy with weight and color (`text-highlighted` / `text-default` / `text-muted` / `text-dimmed`), not with many sizes.
56
+ - Let text wrap rather than truncate important content. When space runs out, stack secondary items under the text.
57
+
58
+ ### Color
59
+ - **Semantic tokens only:** `text-*` (highlighted, default, toned, muted, dimmed), `bg-default` / `bg-grouped` / `bg-cell` / `bg-elevated` / `bg-fill`, `border-default`/`border-separator`, and the Nuxt UI colors (`primary`, `success`, `error`...). No raw palette classes, no hex values. The only exception is Settings icon tiles via `iconColor`.
60
+ - **One accent color, and it means "interactive".** Don't use it for decorative or non-interactive text. Red means destructive or error, nothing else.
61
+ - Light and dark mode are both required. The app follows the system setting: **no in-app theme toggle** (HIG). Never rely on color alone; add an icon or label.
62
+ - `glass` / `glass-bar` / `glass-control` (translucent material) is only for floating UI: tab bar, nav bar and its buttons, menus, toasts. Never for content cards. Menus and popovers have no hard ring, just material and a soft shadow.
63
+
64
+ ### Controls
65
+ - At most one prominent (`solid`) button per view. Everything else is `soft`, `ghost` or `link`. Show priority through style, not size. **A destructive button is never the prominent primary.**
66
+ - Async actions show `loading` on the button itself. Use a verb-form label while it runs if helpful ("Saving…").
67
+ - **`USwitch` only inside a list row.** Outside of lists, use a toggle button.
68
+ - **No radio buttons or checkboxes for choosing options.** Use rows with checkmarks (`MobileListRow :selected`). Selection applies immediately, with no Save button. Checkboxes are only for legal consent.
69
+ - **Segmented control** (`UTabs :content="false"`, already styled): 2–5 short noun labels for closely related views of the *same* content, or for a small set of form values. Never for switching app sections.
70
+ - Pickers: short lists (up to about 7) go in `USelect`/`UDropdownMenu`. Long lists get their own route with search and checkmark rows.
71
+ - Forms: visible labels, inputs stacked at full width, correct `type`/`inputmode`/`autocomplete`/`enterkeyhint`. Never pre-fill passwords. Prefer choices over typed input. Validate on blur, and show errors next to the field explaining how to fix them.
72
+
73
+ ### Feedback and states
74
+ - Show something immediately: skeletons (`USkeleton`) shaped like the content, never a blank screen or a full-page spinner.
75
+ - Success is usually silent, because the UI changes visibly. Toasts are for background results or undo. Keep them short and drop "Success!" headings.
76
+ - Empty states (`UEmpty`, `variant="naked"`) explain the situation and offer exactly one next step.
77
+ - Respect `prefers-reduced-motion` (Nuxt UI already does). Motion is short and purposeful, with no decorative loops.
78
+
79
+ ### Writing
80
+ - Buttons are verbs ("Add Item", "Delete", "Save"), never "OK/Yes/No" when a verb fits. "Cancel" cancels. Title case for buttons, titles and menu items in English; normal German capitalization for German.
81
+ - Say "tap", not "click". Avoid "we", "your" ("Favorites", not "Your Favorites"), and "Oops/Invalid/Error" without an explanation.
82
+
83
+ ## Adapting beyond the phone
84
+ The phone layout is the baseline. From `lg` up, you can swap the tab bar for `UDashboardSidebar` (iPad pattern: tab bar becomes sidebar) and constrain content to about `max-w-2xl mx-auto`. Keep the same functionality in every size; only the arrangement changes.
85
+
86
+ ## Verify
87
+ Test in a 390×844 viewport in light **and** dark mode (Playwright `browser_resize` + `browser_emulate_media`), with real scrolling (large title collapse, glass bars). Open every sheet and menu. Then go through `references/review-checklist.md`. Final check on a real iPhone for safe areas, the keyboard and the 16px zoom rule.
88
+
89
+ ## References
90
+ - `references/patterns.md`: HIG pattern → Nuxt UI recipe with code (nav bars, sheets, action sheets, alerts, search, lists, forms, menus, undo toasts, loading, swipe actions, tablet adaptation).
91
+ - `references/tokens.md`: every token and override in the template and the reasoning behind it, plus how to rebrand.
92
+ - `references/review-checklist.md`: pass/fail list for reviews.
@@ -0,0 +1,18 @@
1
+ export interface DemoItem {
2
+ id: number
3
+ title: string
4
+ notes: string
5
+ priority: 'low' | 'normal' | 'high'
6
+ done: boolean
7
+ updated: string
8
+ }
9
+
10
+ export function useDemoItems() {
11
+ return useState<DemoItem[]>('demo-items', () => [
12
+ { id: 1, title: 'Book flights', notes: 'Berlin → Lisbon, early May', priority: 'high', done: false, updated: 'Today' },
13
+ { id: 2, title: 'Renew passport', notes: 'Appointment at Bürgeramt', priority: 'normal', done: false, updated: 'Yesterday' },
14
+ { id: 3, title: 'Call landlord', notes: 'Heating in the bathroom', priority: 'low', done: true, updated: 'Monday' },
15
+ { id: 4, title: 'Return library books', notes: '', priority: 'low', done: false, updated: 'Sunday' },
16
+ { id: 5, title: 'Plan birthday dinner', notes: 'Table for 8, Friday', priority: 'normal', done: false, updated: 'Oct 2' }
17
+ ])
18
+ }
@@ -0,0 +1,121 @@
1
+ <script setup lang="ts">
2
+ const items = useDemoItems()
3
+ const toast = useToast()
4
+
5
+ const search = ref('')
6
+ const filter = ref('all')
7
+ const filters = [
8
+ { label: 'All', value: 'all' },
9
+ { label: 'Open', value: 'open' },
10
+ { label: 'Done', value: 'done' }
11
+ ]
12
+
13
+ const visible = computed(() => items.value.filter((item) => {
14
+ if (filter.value === 'open' && item.done) return false
15
+ if (filter.value === 'done' && !item.done) return false
16
+ return item.title.toLowerCase().includes(search.value.trim().toLowerCase())
17
+ }))
18
+
19
+ const sheetOpen = ref(false)
20
+ const draft = reactive({ title: '', notes: '', priority: 'normal' as const })
21
+ const priorities = [
22
+ { label: 'Low', value: 'low' },
23
+ { label: 'Normal', value: 'normal' },
24
+ { label: 'High', value: 'high' }
25
+ ]
26
+
27
+ function add() {
28
+ items.value.unshift({ id: Date.now(), ...draft, title: draft.title.trim(), done: false, updated: 'Now' })
29
+ Object.assign(draft, { title: '', notes: '', priority: 'normal' })
30
+ sheetOpen.value = false
31
+ }
32
+
33
+ const menu = [
34
+ [{ label: 'Select', icon: 'i-ph-check-circle' }, { label: 'Sort by Date', icon: 'i-ph-sort-descending' }],
35
+ [{ label: 'Mark All as Done', icon: 'i-ph-checks', onSelect: () => {
36
+ const before = items.value.map(item => item.done)
37
+ items.value.forEach(item => (item.done = true))
38
+ toast.add({
39
+ title: 'All items marked as done',
40
+ actions: [{ label: 'Undo', color: 'neutral', variant: 'soft', onClick: () => items.value.forEach((item, i) => (item.done = before[i]!)) }]
41
+ })
42
+ } }]
43
+ ]
44
+ </script>
45
+
46
+ <template>
47
+ <div>
48
+ <MobileNavBar title="Inbox" large>
49
+ <template #trailing>
50
+ <UDropdownMenu :items="menu" :content="{ align: 'end' }">
51
+ <UButton icon="i-ph-dots-three-bold" color="neutral" variant="ghost" aria-label="More" />
52
+ </UDropdownMenu>
53
+ <UButton icon="i-ph-plus-bold" color="neutral" variant="ghost" aria-label="New Item" @click="sheetOpen = true" />
54
+ </template>
55
+
56
+ <div class="space-y-3">
57
+ <UInput
58
+ v-model="search"
59
+ icon="i-ph-magnifying-glass"
60
+ placeholder="Search items"
61
+ variant="soft"
62
+ type="search"
63
+ enterkeyhint="search"
64
+ class="w-full"
65
+ :ui="{ base: 'bg-fill rounded-full' }"
66
+ />
67
+ <UTabs v-model="filter" :items="filters" :content="false" class="w-full" />
68
+ </div>
69
+ </MobileNavBar>
70
+
71
+ <main class="space-y-8 pt-2">
72
+ <MobileListSection v-if="visible.length">
73
+ <MobileListRow
74
+ v-for="item in visible"
75
+ :key="item.id"
76
+ :title="item.title"
77
+ :subtitle="item.notes || 'No notes'"
78
+ :value="item.updated"
79
+ :to="`/items/${item.id}`"
80
+ :icon="item.done ? 'i-ph-check-circle-fill' : 'i-ph-circle'"
81
+ />
82
+ </MobileListSection>
83
+
84
+ <UEmpty
85
+ v-else
86
+ icon="i-ph-magnifying-glass"
87
+ :title="search ? `No results for “${search}”` : 'Nothing here yet'"
88
+ :description="search ? 'Check the spelling or try a different search.' : 'Items you add show up here.'"
89
+ variant="naked"
90
+ :actions="search ? [] : [{ label: 'Add Item', icon: 'i-ph-plus-bold', onClick: () => { sheetOpen = true } }]"
91
+ />
92
+ </main>
93
+
94
+ <!-- Form sheet: Cancel leading, primary action trailing and disabled until the form is valid -->
95
+ <UDrawer v-model:open="sheetOpen" :handle="true" should-scale-background>
96
+ <template #header>
97
+ <div class="grid w-full grid-cols-[1fr_auto_1fr] items-center">
98
+ <UButton label="Cancel" color="neutral" variant="ghost" class="justify-self-start" @click="sheetOpen = false" />
99
+ <h2 class="text-headline text-highlighted">
100
+ New Item
101
+ </h2>
102
+ <UButton label="Add" :disabled="!draft.title.trim()" class="justify-self-end" @click="add" />
103
+ </div>
104
+ </template>
105
+
106
+ <template #body>
107
+ <div class="space-y-5 pb-2">
108
+ <UFormField label="Title" name="title">
109
+ <UInput v-model="draft.title" placeholder="What needs doing?" autofocus class="w-full" enterkeyhint="done" />
110
+ </UFormField>
111
+ <UFormField label="Notes" name="notes">
112
+ <UTextarea v-model="draft.notes" placeholder="Optional" :rows="3" autoresize class="w-full" />
113
+ </UFormField>
114
+ <UFormField label="Priority" name="priority">
115
+ <UTabs v-model="draft.priority" :items="priorities" :content="false" class="w-full" />
116
+ </UFormField>
117
+ </div>
118
+ </template>
119
+ </UDrawer>
120
+ </div>
121
+ </template>
@@ -0,0 +1,77 @@
1
+ <script setup lang="ts">
2
+ import { MobileActionSheet } from '#components'
3
+
4
+ const route = useRoute()
5
+ const router = useRouter()
6
+ const toast = useToast()
7
+ const overlay = useOverlay()
8
+ const items = useDemoItems()
9
+
10
+ const item = computed(() => items.value.find(i => i.id === Number(route.params.id)))
11
+
12
+ const actionSheet = overlay.create(MobileActionSheet)
13
+
14
+ async function confirmDelete() {
15
+ const choice = await actionSheet.open({
16
+ title: 'This item will be deleted permanently.',
17
+ actions: [{ label: 'Delete Item', value: 'delete', destructive: true }]
18
+ })
19
+ if (choice !== 'delete' || !item.value) return
20
+ const removed = item.value
21
+ items.value = items.value.filter(i => i.id !== removed.id)
22
+ router.back()
23
+ toast.add({ title: `Deleted “${removed.title}”` })
24
+ }
25
+
26
+ function toggleDone() {
27
+ if (!item.value) return
28
+ item.value.done = !item.value.done
29
+ }
30
+
31
+ const menu = computed(() => [
32
+ [{ label: 'Share', icon: 'i-ph-export' }, { label: 'Duplicate', icon: 'i-ph-copy' }],
33
+ [{ label: 'Delete', icon: 'i-ph-trash', color: 'error' as const, onSelect: confirmDelete }]
34
+ ])
35
+ </script>
36
+
37
+ <template>
38
+ <div v-if="item">
39
+ <MobileNavBar :title="item.title" back>
40
+ <template #trailing>
41
+ <UDropdownMenu :items="menu" :content="{ align: 'end' }">
42
+ <UButton icon="i-ph-dots-three-bold" color="neutral" variant="ghost" aria-label="More" />
43
+ </UDropdownMenu>
44
+ </template>
45
+ </MobileNavBar>
46
+
47
+ <main class="space-y-8 pt-4">
48
+ <MobileListSection header="Notes">
49
+ <p class="px-4 py-3 text-body" :class="item.notes ? 'text-default' : 'text-muted'">
50
+ {{ item.notes || 'No notes' }}
51
+ </p>
52
+ </MobileListSection>
53
+
54
+ <MobileListSection header="Details">
55
+ <MobileListRow title="Priority" :value="item.priority[0]!.toUpperCase() + item.priority.slice(1)" />
56
+ <MobileListRow title="Status" :value="item.done ? 'Done' : 'Open'" />
57
+ <MobileListRow title="Last Updated" :value="item.updated" />
58
+ </MobileListSection>
59
+
60
+ <!-- One prominent action, in the thumb zone -->
61
+ <div class="px-4">
62
+ <UButton
63
+ :label="item.done ? 'Mark as Open' : 'Mark as Done'"
64
+ :variant="item.done ? 'soft' : 'solid'"
65
+ size="lg"
66
+ block
67
+ @click="toggleDone"
68
+ />
69
+ </div>
70
+ </main>
71
+ </div>
72
+
73
+ <div v-else>
74
+ <MobileNavBar title="Not Found" back />
75
+ <UEmpty icon="i-ph-question" title="This item doesn’t exist anymore" description="It may have been deleted on another device." variant="naked" />
76
+ </div>
77
+ </template>
@@ -0,0 +1,71 @@
1
+ <script setup lang="ts">
2
+ import { MobileActionSheet } from '#components'
3
+
4
+ const overlay = useOverlay()
5
+ const actionSheet = overlay.create(MobileActionSheet)
6
+ const sortOrder = useState('sort-order', () => 'Date Added')
7
+
8
+ const notifications = ref(true)
9
+ const sounds = ref(false)
10
+ const deleteOpen = ref(false)
11
+
12
+ async function signOut() {
13
+ const choice = await actionSheet.open({
14
+ actions: [{ label: 'Sign Out', value: true, destructive: true }]
15
+ })
16
+ if (choice) navigateTo('/')
17
+ }
18
+ </script>
19
+
20
+ <template>
21
+ <div>
22
+ <MobileNavBar title="Settings" large />
23
+
24
+ <main class="space-y-8 pt-2">
25
+ <MobileListSection>
26
+ <MobileListRow title="Alex Morgan" subtitle="alex@example.com" to="/settings" icon="i-ph-user-circle-fill" />
27
+ </MobileListSection>
28
+
29
+ <MobileListSection header="Notifications" footer="Reminders arrive at the time you set on each item.">
30
+ <MobileListRow title="Allow Notifications" icon="i-ph-bell-simple-fill" icon-color="error">
31
+ <template #trailing>
32
+ <USwitch v-model="notifications" aria-label="Allow Notifications" />
33
+ </template>
34
+ </MobileListRow>
35
+ <MobileListRow title="Sounds" icon="i-ph-speaker-high-fill" icon-color="warning">
36
+ <template #trailing>
37
+ <USwitch v-model="sounds" :disabled="!notifications" aria-label="Sounds" />
38
+ </template>
39
+ </MobileListRow>
40
+ </MobileListSection>
41
+
42
+ <MobileListSection header="Lists">
43
+ <MobileListRow title="Sort Order" :value="sortOrder" to="/settings/sort" icon="i-ph-sort-ascending-bold" icon-color="primary" />
44
+ <MobileListRow title="Archive" to="/settings" icon="i-ph-archive-fill" icon-color="neutral" />
45
+ </MobileListSection>
46
+
47
+ <MobileListSection>
48
+ <MobileListRow title="Sign Out" @click="signOut" />
49
+ </MobileListSection>
50
+
51
+ <MobileListSection footer="Deleting your account removes all items on every device.">
52
+ <MobileListRow title="Delete Account" destructive @click="deleteOpen = true" />
53
+ </MobileListSection>
54
+ </main>
55
+
56
+ <!-- Alert: rare, irreversible, not undoable → the one case for a centered dialog -->
57
+ <UModal
58
+ v-model:open="deleteOpen"
59
+ title="Delete your account?"
60
+ description="All items will be removed from every device. This can’t be undone."
61
+ :close="false"
62
+ :dismissible="false"
63
+ :ui="{ content: 'max-w-[18rem]', header: 'flex-col text-center', footer: 'grid grid-cols-2 gap-2' }"
64
+ >
65
+ <template #footer>
66
+ <UButton label="Cancel" color="neutral" variant="soft" block @click="deleteOpen = false" />
67
+ <UButton label="Delete" color="error" variant="soft" block @click="deleteOpen = false" />
68
+ </template>
69
+ </UModal>
70
+ </div>
71
+ </template>
@@ -0,0 +1,23 @@
1
+ <script setup lang="ts">
2
+ const sortOrder = useState('sort-order', () => 'Date Added')
3
+ const options = ['Date Added', 'Due Date', 'Priority', 'Title']
4
+ </script>
5
+
6
+ <template>
7
+ <div>
8
+ <MobileNavBar title="Sort Order" back="/settings" />
9
+
10
+ <main class="space-y-8 pt-4">
11
+ <!-- Single choice: checkmark rows, selection applies immediately, no Save button -->
12
+ <MobileListSection role="radiogroup" aria-label="Sort Order">
13
+ <MobileListRow
14
+ v-for="option in options"
15
+ :key="option"
16
+ :title="option"
17
+ :selected="sortOrder === option"
18
+ @click="sortOrder = option"
19
+ />
20
+ </MobileListSection>
21
+ </main>
22
+ </div>
23
+ </template>
@@ -0,0 +1,212 @@
1
+ # HIG patterns → Nuxt UI recipes
2
+
3
+ All snippets assume the template is installed. Complete screens: `examples/app/pages/`.
4
+
5
+ ## Contents
6
+ - Screen skeleton
7
+ - Navigation bar
8
+ - Tab bar
9
+ - Sheets (create / edit)
10
+ - Action sheet
11
+ - Alert
12
+ - Menus
13
+ - Search
14
+ - Segmented control
15
+ - Lists (grouped, options, actions)
16
+ - Forms
17
+ - Feedback: toasts, undo, loading, empty states
18
+ - Swipe actions, long press, pull to refresh
19
+ - Tablet / desktop adaptation
20
+
21
+ ## Screen skeleton
22
+
23
+ ```vue
24
+ <template>
25
+ <div>
26
+ <MobileNavBar title="Inbox" large>
27
+ <template #trailing>…</template>
28
+ <!-- default slot: search field / segmented control under the large title -->
29
+ </MobileNavBar>
30
+
31
+ <main class="space-y-8 pt-2">
32
+ <MobileListSection header="…">…</MobileListSection>
33
+ </main>
34
+ </div>
35
+ </template>
36
+ ```
37
+
38
+ The layout already reserves space for the tab bar and safe areas. Pages don't add their own bottom padding.
39
+
40
+ ## Navigation bar (`MobileNavBar`)
41
+
42
+ | Screen | Props |
43
+ |---|---|
44
+ | Tab root (top level) | `large` |
45
+ | Drill-down | `back` (history back, or falls back to `/`) or `back="/parent"` |
46
+ | Full-screen flow (`plain` layout) | `#leading` with a Cancel or Close button |
47
+
48
+ - Leading and trailing buttons each share one **glass capsule**, iOS 26 style. Put only `UButton color="neutral" variant="ghost"` inside. Use icon-only buttons with an `aria-label`, or a short text button.
49
+ - At most about 2 icons trailing. More goes into a "…" `UDropdownMenu`.
50
+ - A primary text action in the bar (Done, Save) is the one place for `variant="solid"` in the bar.
51
+
52
+ ## Tab bar (`MobileTabBar`)
53
+
54
+ ```ts
55
+ const tabs: TabBarItem[] = [
56
+ { label: 'Home', icon: 'i-ph-house', activeIcon: 'i-ph-house-fill', to: '/' },
57
+ { label: 'Search', icon: 'i-ph-magnifying-glass', activeIcon: 'i-ph-magnifying-glass-bold', to: '/search' },
58
+ { label: 'Inbox', icon: 'i-ph-tray', activeIcon: 'i-ph-tray-fill', to: '/inbox', badge: 3 }
59
+ ]
60
+ ```
61
+
62
+ - Single-word labels. Use badges only for genuinely new items.
63
+ - Never hide or disable a tab. If a section is empty, show an empty state inside it.
64
+ - To hide the tab bar during a full-screen flow, use `definePageMeta({ layout: 'plain' })`.
65
+
66
+ ## Sheets (create / edit)
67
+
68
+ Bottom `UDrawer`, with the header built as a 3-column bar:
69
+
70
+ ```vue
71
+ <UDrawer v-model:open="open" should-scale-background>
72
+ <template #header>
73
+ <div class="grid w-full grid-cols-[1fr_auto_1fr] items-center">
74
+ <UButton label="Cancel" color="neutral" variant="ghost" class="justify-self-start" @click="open = false" />
75
+ <h2 class="text-headline text-highlighted">New Item</h2>
76
+ <UButton label="Add" :disabled="!valid" class="justify-self-end" @click="save" />
77
+ </div>
78
+ </template>
79
+ <template #body>…form…</template>
80
+ </UDrawer>
81
+ ```
82
+
83
+ - Cancel on the left, the completing action on the right. Never show Done, Cancel and Back together. Multi-step flows replace Cancel with Back from step 2 on.
84
+ - If there are unsaved changes, confirm before the sheet closes, whether by swipe or Cancel. Use an action sheet ("Discard Changes" in red, then "Keep Editing"), not an alert. Set `:dismissible="false"` while dirty and open the action sheet from Cancel.
85
+
86
+ ## Action sheet (`MobileActionSheet`)
87
+
88
+ ```ts
89
+ import { MobileActionSheet } from '#components'
90
+
91
+ const actionSheet = useOverlay().create(MobileActionSheet)
92
+
93
+ const choice = await actionSheet.open({
94
+ title: 'This photo will be deleted from all your devices.', // optional, one line
95
+ actions: [
96
+ { label: 'Delete Photo', value: 'delete', destructive: true },
97
+ { label: 'Remove from Album', value: 'remove' }
98
+ ]
99
+ })
100
+ if (choice === 'delete') …
101
+ ```
102
+
103
+ Use it for choices about an action the person just started. Destructive options are red, Cancel is added automatically and comes last, and the result is `undefined` when cancelled. No scrolling: keep it to about 4 actions or fewer.
104
+
105
+ ## Alert (`UModal`)
106
+
107
+ Only for rare, irreversible things that can't be undone (account deletion, losing an unsaved document when the app quits).
108
+
109
+ ```vue
110
+ <UModal
111
+ v-model:open="open"
112
+ title="Delete your account?"
113
+ description="All items will be removed from every device. This can’t be undone."
114
+ :close="false"
115
+ :dismissible="false"
116
+ :ui="{ content: 'max-w-[18rem]', header: 'flex-col text-center', footer: 'grid grid-cols-2 gap-2' }"
117
+ >
118
+ <template #footer>
119
+ <UButton label="Cancel" color="neutral" variant="soft" block @click="open = false" />
120
+ <UButton label="Delete" color="error" variant="soft" block @click="remove" />
121
+ </template>
122
+ </UModal>
123
+ ```
124
+
125
+ The title is a question or statement of what happens, not "Error" or "Are you sure?". Buttons are verbs plus "Cancel". The destructive button is never `solid`. For 3 buttons, stack them vertically (`footer: 'flex flex-col gap-2'`).
126
+
127
+ ## Menus
128
+
129
+ - **Nav bar "…"**: `UDropdownMenu` with grouped items (nested arrays). Up to about 3 groups, destructive last with `color: 'error'`. Items get icons either all or none within a group.
130
+ - **Long press on items**: `UContextMenu`. Use only commands relevant to the item, and every command must exist elsewhere too (detail page, nav bar). Never give one item both a context menu and an edit menu.
131
+ - **Labels**: verbs, title case, no articles ("Move to Folder…"). Add an ellipsis when more input follows.
132
+
133
+ ## Search
134
+
135
+ Put an inline search field under the large title, in `MobileNavBar`'s default slot:
136
+
137
+ ```vue
138
+ <UInput
139
+ v-model="q" icon="i-ph-magnifying-glass" placeholder="Search items"
140
+ variant="soft" type="search" enterkeyhint="search" class="w-full"
141
+ :ui="{ base: 'bg-fill rounded-full' }"
142
+ />
143
+ ```
144
+
145
+ - Search as the person types. The placeholder names what's searchable. Show recent searches before typing when that's useful, with a "Clear" action.
146
+ - A no-results state uses `UEmpty` with the query in the title and a hint. Don't offer a "Create" action there unless it's the obvious next step.
147
+ - If search is the main activity of the app, give it its own tab instead.
148
+
149
+ ## Segmented control
150
+
151
+ ```vue
152
+ <UTabs v-model="filter" :items="[{ label: 'All', value: 'all' }, { label: 'Open', value: 'open' }]" :content="false" class="w-full" />
153
+ ```
154
+
155
+ Use 2–5 nouns of similar length, all text or all icons. Use it to switch views of the same data, or as a compact form value. Never use it to navigate between app sections.
156
+
157
+ ## Lists
158
+
159
+ ```vue
160
+ <MobileListSection header="Notifications" footer="Explains the section in one sentence.">
161
+ <MobileListRow title="Allow Notifications" icon="i-ph-bell-simple-fill" icon-color="error">
162
+ <template #trailing><USwitch v-model="on" aria-label="Allow Notifications" /></template>
163
+ </MobileListRow>
164
+ <MobileListRow title="Sort Order" value="Date Added" to="/settings/sort" />
165
+ </MobileListSection>
166
+ ```
167
+
168
+ | Row type | How |
169
+ |---|---|
170
+ | Drill-down | `to` (adds chevron automatically) |
171
+ | Setting with value | `value` + `to` |
172
+ | Toggle | `#trailing` slot with `USwitch` plus `aria-label` |
173
+ | Action | `@click`, tinted text, no chevron. Put it in its own section. |
174
+ | Destructive action | `@click` + `destructive`, in its own section at the bottom |
175
+ | Single choice | `:selected` + `@click`, section `role="radiogroup"`. Applies immediately, no Save. |
176
+ | Read-only metadata | `title` + `value` |
177
+
178
+ - Settings icon tiles (`icon-color`) are for settings-style screens only. Content lists use a plain icon, an avatar (`#leading`-style custom row) or nothing.
179
+ - Long content feeds (more than about 50 rows) still use the inset section, but think about grouping by date with section headers.
180
+ - For a fully custom row, keep the anatomy: `ps-4` row, inset separator on the content wrapper, at least 44px, `active:bg-elevated` when tappable.
181
+
182
+ ## Forms
183
+
184
+ - In a sheet or on a page: `UFormField` per field, stacked, `class="w-full"` on the controls. Use `space-y-5` between fields.
185
+ - Pick the keyboard per field: `type="email"`, `inputmode="numeric|decimal|tel|url"`, `autocomplete="email|name|one-time-code|current-password|new-password"`, `enterkeyhint="next|done|go|search|send"`. Turn off `autocapitalize`/`autocorrect` for codes and handles.
186
+ - Use choices instead of typing: segmented control for 2–5 values, `USelect` for short lists, a pushed checkmark list for long lists, `UInputDate`/`UInputTime` for dates.
187
+ - Disable the completing action until required fields are valid. Validate email on blur and password rules live. The error text says how to fix it ("Use at least 8 characters"), not "Invalid".
188
+ - Never pre-fill a password field. Don't ask for data the platform can give you (geolocation, contacts picker, `autocomplete`).
189
+
190
+ ## Feedback
191
+
192
+ - **Toasts** (`useToast`) drop from the top-center. Keep them short with no "Success!" heading. Use them for background results, undo, or results the person can't see on screen.
193
+ - **Undo instead of confirm**:
194
+ ```ts
195
+ toast.add({ title: 'Item deleted', actions: [{ label: 'Undo', color: 'neutral', variant: 'soft', onClick: restore }] })
196
+ ```
197
+ - **Loading**: on first load, `USkeleton` blocks shaped like the final rows (`h-11 rounded-none` inside a `MobileListSection`). For actions, set `:loading` on the triggering button. Avoid full-screen spinners. If you must wait more than about 2s, say what's happening ("Uploading 3 of 12 photos").
198
+ - **Empty states**: `UEmpty variant="naked"` with an icon, a one-line title, a one-sentence description and at most one action.
199
+ - **Errors**: show them inline next to their cause. A failed screen load gets an empty state with a "Try Again" button.
200
+
201
+ ## Swipe actions, long press, pull to refresh
202
+
203
+ - Swipe-to-delete has no Nuxt UI component. If you build it, keep the same action available in a context menu or on the detail page. Swiping must never be the only way.
204
+ - Long-press menus, pull-to-refresh and pinch gestures: see the **ios-web-polish** skill (timers, `touch-action`, `overscroll-behavior`, reference implementations).
205
+
206
+ ## Tablet / desktop adaptation
207
+
208
+ The phone is the baseline. From `lg` up:
209
+ - Replace `MobileTabBar` with `UDashboardSidebar`, using the same destinations in the same order. Show it with `lg:hidden` / `hidden lg:flex`.
210
+ - Center content: `mx-auto w-full max-w-2xl`. List/detail can become a two-pane `UDashboardPanel` layout.
211
+ - Bottom sheets can become centered `UModal`s (`useMediaQuery('(min-width: 1024px)')`). Keep the same content and buttons.
212
+ - Keep functionality identical; only the arrangement changes.