ship-create 1.3.1 → 1.5.0
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.
- package/create.mjs +347 -166
- package/package.json +1 -1
- package/templates/.claude/commands/build.md +134 -0
- package/templates/.claude/skills/uiux-frontend/SKILL.md +321 -0
- package/templates/.cursorrules +41 -24
- package/templates/.windsurfrules +41 -24
- package/templates/AGENTS.md +41 -24
- package/templates/CLAUDE.md +41 -24
- package/templates/docs/DESIGN_SPEC.md +50 -0
- package/templates/docs/DESIGN_SYSTEM.md +145 -0
- package/templates/docs/tech-stack/STACK_DECISION_MATRIX.md +288 -0
- package/templates/docs/tech-stack/TECH_STACK.md +492 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Read docs, create build spec, and build the MVP fast — home screen first, white theme by default.
|
|
3
|
+
argument-hint: "[feature name — leave blank to build the full MVP]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
You are building this app using The SHIP Method. Move fast — the goal is a working MVP the user can see and react to. Refine later.
|
|
7
|
+
|
|
8
|
+
Argument passed (optional feature focus): "$ARGUMENTS"
|
|
9
|
+
|
|
10
|
+
## Step 1 — Read the project docs
|
|
11
|
+
|
|
12
|
+
Read both files now:
|
|
13
|
+
- `docs/PROJECT.md` — what we're building and for whom
|
|
14
|
+
- `docs/HUMAN_FLOW.md` — how users move through the product
|
|
15
|
+
|
|
16
|
+
## Step 2 — Quick sanity check
|
|
17
|
+
|
|
18
|
+
If PROJECT.md or HUMAN_FLOW.md is missing OR still has `[fill in]` placeholders in Vision, Problem Statement, or Core Screens — stop and say: "Run `/ship` first — I need a filled spec to build from." Otherwise proceed immediately.
|
|
19
|
+
|
|
20
|
+
## Step 2.5 — Four quick choices (one message, one reply)
|
|
21
|
+
|
|
22
|
+
Ask all four in a single message. Wait for one reply, then proceed immediately — no follow-up questions.
|
|
23
|
+
|
|
24
|
+
**1. Site type**
|
|
25
|
+
- `A` Landing page — public, no login needed to browse
|
|
26
|
+
- `B` Member system — login wall, users must sign in first
|
|
27
|
+
|
|
28
|
+
**2. Language**
|
|
29
|
+
- `A` Thai (ภาษาไทย)
|
|
30
|
+
- `B` English
|
|
31
|
+
|
|
32
|
+
**3. Font style**
|
|
33
|
+
- If Thai (choice 2A): `T1` Prompt · `T2` IBM Plex Thai · `T3` Noto Sans Thai · `T4` Anuphan
|
|
34
|
+
- If English (choice 2B): `E1` Modern — Inter / Geist · `E2` Luxury — Playfair Display + DM Sans
|
|
35
|
+
|
|
36
|
+
**4. Color theme** — shadcn/ui standard palettes:
|
|
37
|
+
- `1` Zinc (neutral gray — most common default)
|
|
38
|
+
- `2` Slate (cool blue-gray)
|
|
39
|
+
- `3` Blue (blue accent)
|
|
40
|
+
- `4` Green (green accent)
|
|
41
|
+
- `5` Orange (warm orange accent)
|
|
42
|
+
- `6` Rose (pink/red accent)
|
|
43
|
+
- `7` Violet (purple accent)
|
|
44
|
+
|
|
45
|
+
Defaults if skipped: B · B · T1 (Prompt) for Thai / E1 (Modern) for English · 1 (Zinc).
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Step 3 — Create the build spec (no waiting)
|
|
50
|
+
|
|
51
|
+
Check if `docs/AI_BUILD_SPEC.md` exists. If not, create it now from the docs:
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
# AI Build Spec
|
|
55
|
+
|
|
56
|
+
## Functional Requirements
|
|
57
|
+
[features from MVP Scope in PROJECT.md — one bullet per feature]
|
|
58
|
+
|
|
59
|
+
## Data Model
|
|
60
|
+
[tables/collections derived from features — fields, types, relations]
|
|
61
|
+
|
|
62
|
+
## API Contract
|
|
63
|
+
[routes/actions needed — method, path, purpose, auth required]
|
|
64
|
+
|
|
65
|
+
## Auth
|
|
66
|
+
[derived from HUMAN_FLOW.md Section 5 Key UX Decisions]
|
|
67
|
+
|
|
68
|
+
## Out of scope
|
|
69
|
+
[from PROJECT.md "Out of scope for MVP"]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Write it and move on — do not wait for user confirmation.
|
|
73
|
+
|
|
74
|
+
## Step 4 — Apply shadcn/ui theme + font (no waiting)
|
|
75
|
+
|
|
76
|
+
**Stack: Tailwind CSS v4 + shadcn/ui. Do not write custom HSL tokens manually.**
|
|
77
|
+
|
|
78
|
+
1. Confirm `shadcn/ui` is initialized in the project. If `components/ui/` doesn't exist, run:
|
|
79
|
+
```
|
|
80
|
+
npx shadcn@latest init
|
|
81
|
+
```
|
|
82
|
+
Select the color palette chosen in Step 2.5 during init (or patch `components.json` + `app/globals.css` to match the chosen palette after the fact).
|
|
83
|
+
|
|
84
|
+
2. Apply the chosen color theme to `app/globals.css` using shadcn's CSS variable block for that palette. Palettes available: `zinc` · `slate` · `blue` · `green` · `orange` · `rose` · `violet`. Always use white background (`--background: 0 0% 100%`).
|
|
85
|
+
|
|
86
|
+
3. Apply the chosen font in `app/layout.tsx` and `app/globals.css` via `next/font/google`:
|
|
87
|
+
|
|
88
|
+
**Thai fonts** — set `subsets: ["thai", "latin"]` on all:
|
|
89
|
+
- `T1` Prompt: `weights: ["400","500","600","700"]`
|
|
90
|
+
- `T2` IBM Plex Thai: `weights: ["400","500","600","700"]`
|
|
91
|
+
- `T3` Noto Sans Thai: `weights: ["400","500","600","700"]`
|
|
92
|
+
- `T4` Anuphan: `weights: ["400","500","600","700"]`
|
|
93
|
+
|
|
94
|
+
Assign to `--font-sans`, apply `font-sans` on `<body>`. Thai fonts are single-font stacks — no separate serif needed.
|
|
95
|
+
|
|
96
|
+
**English fonts:**
|
|
97
|
+
- `E1` Modern: Keep Geist if present, otherwise `Inter`. `font-sans` on `<body>`.
|
|
98
|
+
- `E2` Luxury: `Playfair_Display` → `--font-serif` (headings), `DM_Sans` → `--font-sans` (body). Apply `--font-serif` to `h1`–`h3` in global CSS.
|
|
99
|
+
|
|
100
|
+
4. Install any needed shadcn components now: `npx shadcn@latest add button card input label` (add more as needed per HUMAN_FLOW.md screens). Do not build custom components for things shadcn already covers.
|
|
101
|
+
|
|
102
|
+
5. **Fill `docs/DESIGN_SYSTEM.md`** — replace all `[FILL: ...]` placeholders with the actual choices made above (palette name, font, language). Leave the trend section blank for now — it gets filled by the `uiux-frontend` skill in Step 5.
|
|
103
|
+
|
|
104
|
+
6. **Fill `docs/DESIGN_SPEC.md` global decisions** — fill site type, language, font, and palette rows.
|
|
105
|
+
|
|
106
|
+
Do not ask for approval. Proceed immediately.
|
|
107
|
+
|
|
108
|
+
## Step 5 — 5-minute MVP: home screen first, data later
|
|
109
|
+
|
|
110
|
+
**Target: user sees a real-looking screen within 5 minutes. Build UI with static placeholder data first. Wire real data after.**
|
|
111
|
+
|
|
112
|
+
**Before building each screen, apply the `.claude/skills/uiux-frontend/SKILL.md` guidelines** — layout pattern, component selection, typography, states, and copy rules. Do not skip this for any screen.
|
|
113
|
+
|
|
114
|
+
Apply choices from Step 2.5 to every screen built:
|
|
115
|
+
- **Landing page:** `app/page.tsx` is a public page — hero section, features, CTA. No auth.
|
|
116
|
+
- **Member system:** `app/page.tsx` redirects to `/login`. Build login page + middleware. First visible screen = the main dashboard with placeholder data.
|
|
117
|
+
- **Thai:** All labels, headings, buttons, nav, and placeholder copy in Thai.
|
|
118
|
+
- **English:** All copy in English.
|
|
119
|
+
|
|
120
|
+
Build in this order — **stop after step 1 and show the user, then continue:**
|
|
121
|
+
1. **Home/entry screen** — replace `app/page.tsx` with static placeholder UI. Announce: "MVP home screen done — here's what it looks like. Continuing with data layer…"
|
|
122
|
+
2. **Database schema** (`lib/db/schema.*.ts`)
|
|
123
|
+
3. **Server actions / API routes**
|
|
124
|
+
4. **Remaining pages** — one screen at a time per HUMAN_FLOW.md
|
|
125
|
+
5. **Wire real data** — replace placeholders with real data layer calls
|
|
126
|
+
|
|
127
|
+
After each screen: one line on what was built, one line on what's next. No long summaries.
|
|
128
|
+
|
|
129
|
+
## Rules
|
|
130
|
+
|
|
131
|
+
- Never invent business logic not in the spec — if unclear, make a reasonable assumption and note it.
|
|
132
|
+
- If a code change conflicts with `docs/AI_BUILD_SPEC.md`, flag it in one sentence and proceed with the most reasonable interpretation.
|
|
133
|
+
- Speed over perfection — working UI with placeholder data beats perfect code the user can't see yet.
|
|
134
|
+
- **No unnecessary libraries** — before adding any `npm install`, ask: "does Next.js, Tailwind, or shadcn already cover this?" If yes, use what's already there. Allowed additions: `next/font/google` (fonts), `zod` + `react-hook-form` (forms, included with shadcn), `lucide-react` (icons, included with shadcn). Everything else requires explicit justification. Never add: `axios` (use `fetch`), `lodash` (use native JS), `moment`/`dayjs` (use `Intl`), `framer-motion` (use CSS transforms + Tailwind transitions first), `styled-components`/`emotion` (Tailwind is the CSS layer).
|
|
@@ -0,0 +1,321 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: uiux-frontend
|
|
3
|
+
description: UI/UX design guidance for Next.js + Tailwind v4 + shadcn/ui projects. Invoke before building any screen. Fetches current trends, auto-selects the best one for the project, then applies layout, component, and copy guidance.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UI/UX Frontend Skill
|
|
7
|
+
|
|
8
|
+
Design guidance for **Next.js + Tailwind CSS v4 + shadcn/ui** projects. Runs in 3 phases: (0) fetch current trends, (1) auto-select + declare, (2) implement.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Phase 0 — Fetch current trends (every invocation, no skipping)
|
|
13
|
+
|
|
14
|
+
Before designing any screen, do a web search to get the freshest UI/UX trend signal:
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
search: "UI UX design trends 2025 site:nngroup.com OR site:smashingmagazine.com OR site:awwwards.com OR site:uxdesign.cc"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Scan the results for any trends that have risen or fallen since the base catalog below. Note any new entrant that appears in ≥ 2 sources. This keeps designs current — do not skip this step.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Phase 1 — Auto-select the trend (do not ask the user)
|
|
25
|
+
|
|
26
|
+
Read `docs/PROJECT.md` for product type, audience, and tone. Cross-reference with the **Trend Catalog** below. Pick **one primary trend** and optionally one supporting micro-trend. Announce the choice in one sentence before writing any code:
|
|
27
|
+
|
|
28
|
+
> "Using **[Trend Name]** — suits [product type] for [audience reason]."
|
|
29
|
+
|
|
30
|
+
### Trend Catalog
|
|
31
|
+
|
|
32
|
+
#### 🎨 Visual & Tactile Aesthetics
|
|
33
|
+
|
|
34
|
+
**Tactile Maximalism (Squishy UI)**
|
|
35
|
+
Soft 3D shapes, inflated elements, playful depth, bold saturated colors, spring-like hover states.
|
|
36
|
+
- Best for: consumer apps, gaming, creative tools, young (18–30) audience
|
|
37
|
+
- Avoid: finance, healthcare, enterprise admin
|
|
38
|
+
- Tailwind implementation: `rounded-3xl shadow-2xl scale-[1.02] hover:scale-105 transition-transform duration-200`, bold `bg-[color]` fills, thick borders `border-4`
|
|
39
|
+
|
|
40
|
+
**Intentional Imperfection**
|
|
41
|
+
Hand-drawn strokes, organic shapes, slight rotation/misalignment, textured backgrounds, ink-style illustrations.
|
|
42
|
+
- Best for: creative agencies, cultural brands, portfolios, artisan products
|
|
43
|
+
- Avoid: SaaS dashboards, fintech, legal
|
|
44
|
+
- Tailwind implementation: `rotate-[-1deg]`, `skew-x-1`, SVG hand-drawn border overlays, `bg-[url('/texture.png')] bg-repeat opacity-10`
|
|
45
|
+
|
|
46
|
+
**Liquid Glass & Glassmorphism**
|
|
47
|
+
Frosted glass panels, translucent cards, blur backdrop, subtle borders on glass surface.
|
|
48
|
+
- Best for: premium apps, fintech, luxury SaaS, iOS-style products
|
|
49
|
+
- Avoid: heavy data tables, accessibility-critical flows (low contrast risk — add `backdrop-blur` + solid text)
|
|
50
|
+
- Tailwind implementation: `bg-white/10 backdrop-blur-md border border-white/20 shadow-lg`, ensure text contrast with `text-white drop-shadow-sm` or `text-gray-900` on light blur
|
|
51
|
+
|
|
52
|
+
**Retrofuturism**
|
|
53
|
+
Neon accents on dark base, grid/scanline overlays, monospace fonts mixed with modern sans, CRT glow effects.
|
|
54
|
+
- Best for: AI tools, dev products, tech startups, edgy consumer apps
|
|
55
|
+
- Avoid: healthcare, legal, conservative brands
|
|
56
|
+
- Tailwind implementation: `bg-gray-950 text-green-400`, `font-mono`, `shadow-[0_0_20px_rgba(74,222,128,0.5)]`, CSS `::before` scanline overlay
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
#### ⚙️ Function & Experience
|
|
61
|
+
|
|
62
|
+
**Spatial Design**
|
|
63
|
+
Elements appear to exist in 3D space — parallax layers, perspective transforms, depth through scale + shadow, immersive scrolling.
|
|
64
|
+
- Best for: product showcases, portfolio sites, hero sections, tech launches
|
|
65
|
+
- Avoid: CRUD admin panels, form-heavy apps
|
|
66
|
+
- Tailwind implementation: `perspective-1000` (custom CSS), `translate-z-[40px]` on hover via `transform-gpu`, `shadow-2xl` depth layers, scroll-driven animation with CSS `@keyframes`
|
|
67
|
+
|
|
68
|
+
**Calm Design & Strategic Minimalism**
|
|
69
|
+
Maximum whitespace, restrained palette (2–3 colors), no decorative elements, typography as the main visual element.
|
|
70
|
+
- Best for: healthcare, productivity, focus tools, wellness, legal SaaS
|
|
71
|
+
- Avoid: marketing pages that need energy, entertainment
|
|
72
|
+
- Tailwind implementation: `max-w-prose mx-auto`, `text-gray-500` for supporting text, `border-b border-gray-100` dividers, avoid shadows — use whitespace for separation
|
|
73
|
+
|
|
74
|
+
**Command Palettes & Unified Search**
|
|
75
|
+
Global `⌘K` search overlay that routes to any action, page, or record. Reduces nav depth, enables power-user flow.
|
|
76
|
+
- Best for: SaaS dashboards, dev tools, data products with many entities
|
|
77
|
+
- Avoid: simple forms, landing pages, consumer apps with < 10 routes
|
|
78
|
+
- Tailwind implementation: Use `cmdk` library + shadcn `Command` component, `fixed inset-0 bg-black/50 flex items-start justify-center pt-32`, trigger via `useEffect` on `⌘K`
|
|
79
|
+
|
|
80
|
+
**Bento Grids**
|
|
81
|
+
Asymmetric card grid where different-sized cells showcase features, metrics, or media — like a magazine layout.
|
|
82
|
+
- Best for: dashboards, feature showcases, portfolios, SaaS landing pages
|
|
83
|
+
- Avoid: long-form content, step-by-step flows
|
|
84
|
+
- Tailwind implementation: `grid grid-cols-3 gap-4 auto-rows-[minmax(160px,auto)]`, mix `col-span-2 row-span-2` for hero cells, shadcn `Card` in each cell
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
#### 🤖 Typography & AI
|
|
89
|
+
|
|
90
|
+
**Expressive Typography**
|
|
91
|
+
Large (100px+) hero type, variable font weights, type as graphic element, kinetic text on scroll, tight tracking on display sizes.
|
|
92
|
+
- Best for: landing pages, marketing sites, portfolios, brand-forward products
|
|
93
|
+
- Avoid: data-dense UIs, forms, admin panels
|
|
94
|
+
- Tailwind implementation: `text-7xl lg:text-9xl font-black tracking-tighter leading-none`, variable fonts via CSS `font-variation-settings`, `mix-blend-multiply` for type overlays
|
|
95
|
+
|
|
96
|
+
**Seamless AI Infrastructure**
|
|
97
|
+
Streaming text (typewriter), skeleton-to-real transitions, inline AI suggestions, confidence indicators, generative placeholders.
|
|
98
|
+
- Best for: AI SaaS, copilot tools, any product with AI-generated content
|
|
99
|
+
- Avoid: non-tech products, forms where instant response is expected
|
|
100
|
+
- Tailwind implementation: `animate-pulse` for streaming state, word-by-word reveal via JS interval, `border-l-2 border-primary pl-3` for AI response thread, `opacity-50` for low-confidence content
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
### Auto-selection decision matrix
|
|
105
|
+
|
|
106
|
+
| Project type | Primary trend | Supporting |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| AI / copilot SaaS | Seamless AI Infrastructure | Command Palettes |
|
|
109
|
+
| B2B dashboard / admin | Calm Design & Strategic Minimalism | Bento Grids |
|
|
110
|
+
| Consumer app (young) | Tactile Maximalism | Expressive Typography |
|
|
111
|
+
| Premium / luxury brand | Liquid Glass | Expressive Typography |
|
|
112
|
+
| Creative agency / portfolio | Intentional Imperfection | Spatial Design |
|
|
113
|
+
| Dev tool / CLI product | Retrofuturism | Command Palettes |
|
|
114
|
+
| Healthcare / wellness | Calm Design & Strategic Minimalism | — |
|
|
115
|
+
| Feature showcase landing page | Bento Grids | Expressive Typography |
|
|
116
|
+
| Tech startup landing | Spatial Design | Expressive Typography |
|
|
117
|
+
| Marketplace / e-commerce | Tactile Maximalism | Bento Grids |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Phase 2 — Implement the screen
|
|
122
|
+
|
|
123
|
+
After announcing the trend:
|
|
124
|
+
|
|
125
|
+
1. **Update `docs/DESIGN_SYSTEM.md`** — fill in the `UI Trend` section (trend name, reason, implementation rules, scope) if not already done.
|
|
126
|
+
2. **Update `docs/DESIGN_SPEC.md`** — add a screen entry for the screen being built. Fill all fields before writing code. Mark `Status: in-progress`.
|
|
127
|
+
3. Build the screen.
|
|
128
|
+
4. After screen is done, update the DESIGN_SPEC entry: mark `Status: done`, tick off states (`✓`), fill in notes.
|
|
129
|
+
|
|
130
|
+
Then apply all sections below.
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## A. Think user-first before touching code
|
|
135
|
+
|
|
136
|
+
Answer these before laying out any screen:
|
|
137
|
+
- Who is the user and what state are they in when they arrive?
|
|
138
|
+
- What is the ONE thing they must accomplish on this screen?
|
|
139
|
+
- Where do they come from, and where do they go next?
|
|
140
|
+
- What does "success" look like for them (not the business)?
|
|
141
|
+
|
|
142
|
+
If you can't answer these from `docs/HUMAN_FLOW.md` → reread it, don't guess.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## B. Layout patterns by screen type
|
|
147
|
+
|
|
148
|
+
### Landing page (public)
|
|
149
|
+
```
|
|
150
|
+
Hero → Value props (3 columns) → Social proof → CTA section → Footer
|
|
151
|
+
```
|
|
152
|
+
- Hero: full-width, headline + subheadline + primary button. Apply trend here most visibly.
|
|
153
|
+
- Value props: shadcn `Card` or Bento grid cells
|
|
154
|
+
- CTA: high-contrast button
|
|
155
|
+
- Mobile: single column, buttons full width
|
|
156
|
+
|
|
157
|
+
### Dashboard (member system)
|
|
158
|
+
```
|
|
159
|
+
Sidebar nav (md+) | Top bar | Main content area
|
|
160
|
+
```
|
|
161
|
+
- Sidebar: 240px, `bg-sidebar` token, active state via `aria-current="page"`
|
|
162
|
+
- Top bar: breadcrumb left, avatar/action right + optional `⌘K` trigger
|
|
163
|
+
- Content: `max-w-screen-xl px-6 py-8`. Bento grid for KPI cards, shadcn `Table` for lists
|
|
164
|
+
|
|
165
|
+
### Login / auth screen
|
|
166
|
+
```
|
|
167
|
+
Centered card (max-w-sm) — logo → heading → form → submit → helper link
|
|
168
|
+
```
|
|
169
|
+
- shadcn `Card` + `CardContent`. Apply trend subtly (background, not form itself).
|
|
170
|
+
- Form: `Label` + `Input` stacked, `Button` full-width
|
|
171
|
+
|
|
172
|
+
### Form / settings screen
|
|
173
|
+
```
|
|
174
|
+
Page heading → section groups → save action at bottom
|
|
175
|
+
```
|
|
176
|
+
- Group fields with section cards. Inline errors via shadcn `FormMessage`.
|
|
177
|
+
- Save button: primary, right-aligned
|
|
178
|
+
|
|
179
|
+
### List / table screen
|
|
180
|
+
```
|
|
181
|
+
Toolbar (search + filter + action) → Table or card grid → Pagination
|
|
182
|
+
```
|
|
183
|
+
- shadcn `Table` for structured data, card grid for visual items
|
|
184
|
+
- Empty state: centered icon + message + CTA
|
|
185
|
+
- Loading: shadcn `Skeleton` rows
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## C. Typography rules
|
|
190
|
+
|
|
191
|
+
### Thai fonts (Prompt / IBM Plex Thai / Noto Sans Thai / Anuphan)
|
|
192
|
+
Single-font stack, `font-sans` everywhere.
|
|
193
|
+
|
|
194
|
+
| Element | Class |
|
|
195
|
+
|---------|-------|
|
|
196
|
+
| Page title h1 | `text-3xl font-bold` |
|
|
197
|
+
| Section heading h2 | `text-xl font-semibold` |
|
|
198
|
+
| Body | `text-base font-normal leading-relaxed` |
|
|
199
|
+
| Caption | `text-sm text-muted-foreground` |
|
|
200
|
+
| Button | `text-sm font-medium` |
|
|
201
|
+
|
|
202
|
+
> Thai script needs `leading-relaxed` or higher. Never go below `text-base` on mobile.
|
|
203
|
+
|
|
204
|
+
### English — Modern (Inter / Geist)
|
|
205
|
+
| Element | Class |
|
|
206
|
+
|---------|-------|
|
|
207
|
+
| Page title h1 | `text-3xl font-bold tracking-tight` |
|
|
208
|
+
| Section heading h2 | `text-xl font-semibold` |
|
|
209
|
+
| Body | `text-base font-normal leading-relaxed` |
|
|
210
|
+
| Caption | `text-sm text-muted-foreground` |
|
|
211
|
+
| Button | `text-sm font-medium` |
|
|
212
|
+
|
|
213
|
+
### English — Luxury (Playfair Display + DM Sans)
|
|
214
|
+
| Element | Class |
|
|
215
|
+
|---------|-------|
|
|
216
|
+
| Page title h1 | `font-serif text-3xl font-bold tracking-wide` |
|
|
217
|
+
| Section heading h2 | `font-serif text-xl font-semibold tracking-wide` |
|
|
218
|
+
| Body | `text-base font-normal leading-relaxed` |
|
|
219
|
+
| Caption | `text-sm text-muted-foreground` |
|
|
220
|
+
| Button | `text-sm font-medium tracking-wide uppercase` |
|
|
221
|
+
|
|
222
|
+
For **Expressive Typography** trend: override h1 to `text-7xl lg:text-9xl font-black tracking-tighter leading-none` on hero sections only.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## D. Spacing & sizing
|
|
227
|
+
|
|
228
|
+
- Page padding: `px-4 sm:px-6 lg:px-8`
|
|
229
|
+
- Section gap: `space-y-8` or `gap-8`
|
|
230
|
+
- Card padding: `p-6`
|
|
231
|
+
- Form fields: `space-y-4`
|
|
232
|
+
- Min touch target: `h-11` (44px)
|
|
233
|
+
- Min body text: `text-base` on mobile
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## E. shadcn/ui component map
|
|
238
|
+
|
|
239
|
+
| Need | Component |
|
|
240
|
+
|------|-----------|
|
|
241
|
+
| Navigation | `NavigationMenu` or `<nav>` + Link |
|
|
242
|
+
| Data entry | `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroup` |
|
|
243
|
+
| Form | `Form` (react-hook-form + zod) |
|
|
244
|
+
| Actions | `Button` (default / outline / ghost / destructive) |
|
|
245
|
+
| Feedback | `Toast`, `Alert` |
|
|
246
|
+
| Modals | `Dialog`, `AlertDialog` |
|
|
247
|
+
| Data display | `Table`, `Card`, `Badge` |
|
|
248
|
+
| Loading | `Skeleton` |
|
|
249
|
+
| Sidebar (mobile) | `Sheet` |
|
|
250
|
+
| Global search | `Command` (cmdk) |
|
|
251
|
+
| Dropdowns | `DropdownMenu` |
|
|
252
|
+
|
|
253
|
+
Do not build custom versions of anything shadcn covers.
|
|
254
|
+
|
|
255
|
+
**Library rule — always check before installing:**
|
|
256
|
+
|
|
257
|
+
| Need | Use this — NOT a new library |
|
|
258
|
+
|------|------------------------------|
|
|
259
|
+
| HTTP requests | Native `fetch` |
|
|
260
|
+
| Date formatting | `Intl.DateTimeFormat` |
|
|
261
|
+
| Array/object utilities | Native JS (`.map`, `.filter`, `.reduce`) |
|
|
262
|
+
| Icons | `lucide-react` (already in shadcn) |
|
|
263
|
+
| Animation | CSS `transition` + Tailwind classes first; CSS `@keyframes` for complex |
|
|
264
|
+
| Forms + validation | `react-hook-form` + `zod` (already in shadcn `Form`) |
|
|
265
|
+
| Global search / cmd palette | shadcn `Command` (uses cmdk internally — do not install cmdk separately) |
|
|
266
|
+
| Fonts | `next/font/google` |
|
|
267
|
+
|
|
268
|
+
Only install a new library if no existing solution covers the need. Mention it explicitly when you do.
|
|
269
|
+
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
## F. UI copy rules
|
|
273
|
+
|
|
274
|
+
### Thai
|
|
275
|
+
- ปุ่ม: กริยาสั้น — "บันทึก", "เข้าสู่ระบบ", "ดูเพิ่มเติม"
|
|
276
|
+
- หัวข้อ: ≤ 10 คำ
|
|
277
|
+
- Placeholder: ตัวอย่างจริง — "กรอกชื่อ-นามสกุล" ไม่ใช่ "กรอกข้อมูล"
|
|
278
|
+
- Error: บอกปัญหาและวิธีแก้ — "กรุณากรอกอีเมลให้ถูกต้อง"
|
|
279
|
+
- Empty: สั่งทำได้ทันที — "ยังไม่มีรายการ — กด 'เพิ่มรายการ' เพื่อเริ่มต้น"
|
|
280
|
+
|
|
281
|
+
### English
|
|
282
|
+
- Buttons: verb-first — "Save changes", "Sign in", "View all"
|
|
283
|
+
- Headings: ≤ 8 words, sentence case
|
|
284
|
+
- Placeholders: real example — "Enter your full name"
|
|
285
|
+
- Error: what + fix — "Email already in use. Try signing in instead."
|
|
286
|
+
- Empty: actionable — "No items yet — click 'Add item' to get started"
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## G. States (all 4 required on every screen)
|
|
291
|
+
|
|
292
|
+
| State | Implementation |
|
|
293
|
+
|-------|----------------|
|
|
294
|
+
| Loading | `Skeleton` matching real content shape |
|
|
295
|
+
| Empty | Centered icon + message + primary CTA |
|
|
296
|
+
| Error | `Alert` destructive + retry action |
|
|
297
|
+
| Success | `Toast` or inline confirmation |
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## H. Accessibility minimum
|
|
302
|
+
|
|
303
|
+
- Keyboard-navigable (`Tab` order = visual order)
|
|
304
|
+
- Icon-only buttons have `aria-label`
|
|
305
|
+
- Every input has a visible `<Label>`
|
|
306
|
+
- Color contrast ≥ 4.5:1 (shadcn defaults pass; glassmorphism — verify manually)
|
|
307
|
+
- Images have `alt` (or `alt=""` if decorative)
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
## I. Revenue link check (before closing any screen)
|
|
312
|
+
|
|
313
|
+
| Screen | Revenue connection |
|
|
314
|
+
|--------|--------------------|
|
|
315
|
+
| Landing page | Conversion — CTA → sign-up / purchase |
|
|
316
|
+
| Login / sign-up | Activation — user reaches product |
|
|
317
|
+
| Dashboard | Retention — user sees value, returns |
|
|
318
|
+
| Settings / billing | Revenue — upgrade path, churn prevention |
|
|
319
|
+
| Empty state | Activation — first action drives retention |
|
|
320
|
+
|
|
321
|
+
If a screen has no revenue link, flag it before spending time on it.
|
package/templates/.cursorrules
CHANGED
|
@@ -1,56 +1,73 @@
|
|
|
1
1
|
# SHIP Agent Rules
|
|
2
2
|
|
|
3
|
-
**This file is the canonical ruleset.** Copies of this exact content live at `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` so that whichever AI coding tool opens this repository, it picks up these rules automatically
|
|
3
|
+
**This file is the canonical ruleset for this project.** Copies of this exact content live at `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, and `.windsurfrules` so that whichever AI coding tool opens this repository, it picks up these rules automatically.
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
## What This
|
|
7
|
+
## What This Project Is
|
|
8
8
|
|
|
9
|
-
This
|
|
9
|
+
This project was scaffolded with **The SHIP Method** — a four-phase discipline for building products with AI:
|
|
10
10
|
|
|
11
11
|
```
|
|
12
12
|
S — STRUCTURE → H — HUMAN FLOW → I — INSTRUCTION → P — PUBLISH
|
|
13
13
|
(what & why) (the experience) (AI-ready specs) (ship it)
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
All docs live under `docs/`:
|
|
17
|
+
|
|
18
|
+
| File | Purpose |
|
|
19
|
+
|---|---|
|
|
20
|
+
| `docs/PROJECT.md` | What & why — vision, audience, problem, MVP scope |
|
|
21
|
+
| `docs/HUMAN_FLOW.md` | How users move through the product, screen by screen |
|
|
22
|
+
| `docs/AI_BUILD_SPEC.md` | Functional requirements, data model, API contract (created at build time) |
|
|
23
|
+
| `docs/tech-stack/STACK_DECISION_MATRIX.md` | How to choose databases, auth, hosting, etc. |
|
|
24
|
+
| `docs/tech-stack/TECH_STACK.md` | Full stack reference for this project type |
|
|
25
|
+
| `docs/PROMPTS.md` | Full SHIP prompt chain (Stages 1-6) for reference |
|
|
26
|
+
|
|
27
|
+
**For UI/design decisions:** invoke the `ui-ux-pro-max` skill — it provides palette, typography, component patterns, and layout guidance specific to this project type. Do not rely on generic static design files.
|
|
17
28
|
|
|
18
29
|
## Mandatory Behavior for Any AI Agent Working in This Repo
|
|
19
30
|
|
|
20
31
|
1. **Check Structure and Human Flow before generating application code.**
|
|
21
|
-
-
|
|
22
|
-
- If either is missing, or still contains unfilled `[bracket placeholders]` in its core sections (Vision, Problem Statement, MVP Scope;
|
|
23
|
-
- Exception: scaffolding,
|
|
32
|
+
- Read `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` at the start of every session.
|
|
33
|
+
- If either is missing, or still contains unfilled `[fill in]` / `[bracket placeholders]` in its core sections (Vision, Problem Statement, MVP Scope; User Journey, Core Screens), **do not generate feature code**. Instead, run `/ship` to guide the user through filling the gaps.
|
|
34
|
+
- Exception: scaffolding, config files, and infra setup are fine to generate at any time — the gate is on *feature/business logic* code only.
|
|
24
35
|
|
|
25
|
-
2. **
|
|
36
|
+
2. **Use `docs/AI_BUILD_SPEC.md` as the source of truth** for functional requirements, data model, and API contract once it exists. If a user's code request conflicts with it, flag the conflict instead of silently overriding the spec.
|
|
26
37
|
|
|
27
38
|
3. **Use the right reference file for the job:**
|
|
28
39
|
| Need | File |
|
|
29
40
|
|---|---|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
33
|
-
|
|
|
34
|
-
|
|
|
41
|
+
| Vision, audience, MVP scope | `docs/PROJECT.md` |
|
|
42
|
+
| User flow, screens | `docs/HUMAN_FLOW.md` |
|
|
43
|
+
| Functional requirements, data model | `docs/AI_BUILD_SPEC.md` |
|
|
44
|
+
| Stack choice | `docs/tech-stack/STACK_DECISION_MATRIX.md` |
|
|
45
|
+
| UI/design decisions | invoke `ui-ux-pro-max` skill — derives palette, font, components from the project context |
|
|
46
|
+
| Product-type feature checklist | `docs/*_TEMPLATE.md` |
|
|
35
47
|
|
|
36
|
-
4. **After generating a new feature**, remind the user to
|
|
48
|
+
4. **After generating a new feature**, remind the user to update `docs/PROJECT.md` Section 6 (MVP Scope) if scope changed.
|
|
37
49
|
|
|
38
50
|
5. **If the user explicitly insists on skipping the gate** ("just build it, skip the docs"), comply — but say once, briefly, what's being skipped and why it usually causes rework later. Don't refuse repeatedly or lecture.
|
|
39
51
|
|
|
40
|
-
6. **Never invent business facts** (market size, pricing, real metrics, real user quotes)
|
|
52
|
+
6. **Never invent business facts** (market size, pricing, real metrics, real user quotes). Draft clearly-labeled `[TBD: ...]` placeholders or ask the user.
|
|
41
53
|
|
|
42
|
-
7. **Once the spec is complete,
|
|
43
|
-
|
|
44
|
-
- **Home:**
|
|
45
|
-
-
|
|
54
|
+
7. **Once the spec is complete, apply white theme and replace the home screen — do this first, before any features.**
|
|
55
|
+
When `docs/PROJECT.md` and `docs/HUMAN_FLOW.md` are filled and `docs/AI_BUILD_SPEC.md` exists:
|
|
56
|
+
- **Home first:** Replace the starter kit's generic `app/page.tsx` immediately with the real entry point from `docs/HUMAN_FLOW.md`. This is always the first build output so the user sees something real right away.
|
|
57
|
+
- **Theme (shadcn/ui):** Use Tailwind CSS v4 + shadcn/ui. Apply the user's chosen shadcn color palette (zinc/slate/blue/green/orange/rose/violet) via its CSS variable block in `app/globals.css`. Always white background. Font: modern (Inter/Geist) or luxury (Playfair Display + DM Sans). Do not write custom HSL tokens manually.
|
|
58
|
+
- See `.claude/skills/ship-method/theme-guide.md` for product-type → palette reference.
|
|
46
59
|
|
|
47
60
|
## Quick Orientation for a New Agent Session
|
|
48
61
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
62
|
+
1. Read `docs/PROJECT.md` to learn what's being built and for whom.
|
|
63
|
+
2. Read `docs/HUMAN_FLOW.md` to understand the user experience.
|
|
64
|
+
3. Check if `docs/AI_BUILD_SPEC.md` exists — if yes, read it for the technical contract.
|
|
65
|
+
4. Then proceed with what the user asked, applying the rules above.
|
|
66
|
+
|
|
67
|
+
**Shortcut commands available:**
|
|
68
|
+
- `/ship` — interactive gate-by-gate guide through Structure → Human Flow → Instruction → Publish
|
|
69
|
+
- `/build` — assumes docs are filled, creates build spec and starts coding the MVP
|
|
53
70
|
|
|
54
71
|
## Source
|
|
55
72
|
|
|
56
|
-
|
|
73
|
+
This project was created with `npx ship-create`. The SHIP Method OS lives at github.com/nireadaddy/the-ship-method-os.
|