create-issflow 1.0.0 → 1.0.2

package/template/.claude/skills/karpathy-guidelines/SKILL.md

@@ -1,34 +1,34 @@
----
-name: karpathy-guidelines
-description: Coding and debugging discipline. Apply on every coding and debug task.
----
-
-# karpathy-guidelines
-
-Apply on every coding + debug task. Caveman ULTRA mode.
-
-## Coding
-- Smallest change that works. No speculative abstraction. No "while I'm here".
-- Make it run, then make it right, then make it fast — in that order.
-- One concern per change. If the diff does two things, split it.
-- Read before write — understand the existing code path before editing.
-- Name things for what they are. Delete dead code, don't comment it out.
-- Prefer boring, obvious solutions over clever ones.
-
-## Debugging
-- Reproduce first.
-- One hypothesis at a time. State it before changing anything.
-- Change one variable, observe, conclude. No shotgun edits.
-- Read the actual error and stack — top to bottom — before theorizing.
-- When stuck: the bug is somewhere you're sure it isn't. Check assumptions.
-- 3 failed attempts -> stop poking, go research.
-
-## Honesty
-- Don't claim it works until you ran it.
-- "I don't know yet" is valid — say it instead of guessing.
-- A failing test is information. Don't edit the test to hide it.
-- Surface uncertainty to the orchestrator; don't paper over it.
-
-## Verification
-- Every change gets run. Lint/typecheck/smoke at minimum.
-- The real test is written blind by test-author — your own run is just sanity.
+---
+name: karpathy-guidelines
+description: Coding and debugging discipline. Apply on every coding and debug task.
+---
+
+# karpathy-guidelines
+
+Apply on every coding + debug task. Caveman ULTRA mode.
+
+## Coding
+- Smallest change that works. No speculative abstraction. No "while I'm here".
+- Make it run, then make it right, then make it fast — in that order.
+- One concern per change. If the diff does two things, split it.
+- Read before write — understand the existing code path before editing.
+- Name things for what they are. Delete dead code, don't comment it out.
+- Prefer boring, obvious solutions over clever ones.
+
+## Debugging
+- Reproduce first.
+- One hypothesis at a time. State it before changing anything.
+- Change one variable, observe, conclude. No shotgun edits.
+- Read the actual error and stack — top to bottom — before theorizing.
+- When stuck: the bug is somewhere you're sure it isn't. Check assumptions.
+- 3 failed attempts -> stop poking, go research.
+
+## Honesty
+- Don't claim it works until you ran it.
+- "I don't know yet" is valid — say it instead of guessing.
+- A failing test is information. Don't edit the test to hide it.
+- Surface uncertainty to the orchestrator; don't paper over it.
+
+## Verification
+- Every change gets run. Lint/typecheck/smoke at minimum.
+- The real test is written blind by test-author — your own run is just sanity.

package/template/.claude/skills/ux-design/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ux-design
+description: >
+  The iStartSoft UX cookbook + wireframe baseline. A checklist an agent uses to
+  VALIDATE generated UI so it does not drift outside the design frame. Use on
+  every UI-facing task: building a screen/component, reviewing a UI diff, or
+  before a frontend phase closes. Triggers: "ui", "screen", "component",
+  "layout", "design", "ux", "wireframe", "responsive", "accessib", "a11y",
+  "ตรวจดีไซน์", "หน้าจอ".
+---
+
+# ux-design — cookbook + wireframe frame
+
+Caveman ULTRA mode. UI conforms to the FRAME. Build or change UI -> run this
+cookbook before you call it done. Drift outside the wireframe = defect, not
+creative liberty (METHODOLOGY hard rule 9).
+
+Read `wireframe-template.md` (same dir) when starting a new screen — it is the
+canonical low-fidelity baseline every screen must map to. Read it on demand only.
+
+-----
+
+## When to apply
+
+- Building a screen / page / component.
+- Reviewing a UI diff (the "ตรวจ" pass).
+- CLOSE gate of any frontend phase — the cookbook check MUST pass.
+
+Order: **wireframe first** (does the layout match the baseline frame?) ->
+**cookbook** (do the details obey the system?). Never invent layout the
+wireframe does not have. If the design truly needs a frame the wireframe lacks,
+STOP and update the wireframe baseline first (a design decision -> `log-decision`).
+
+-----
+
+## The cookbook (check every item)
+
+### 1. Design tokens — no raw values
+- Color / spacing / radius / type / shadow come from named tokens, never
+  hard-coded hex / px literals scattered in components.
+- One source of truth (CSS vars / theme file). New token? add it to the source,
+  don't inline it.
+
+### 2. Spacing scale — 8pt grid
+- All spacing is a multiple of 4px, prefer 8 (4 · 8 · 12 · 16 · 24 · 32 · 48 · 64).
+- No magic margins (`margin: 7px`). Off-grid spacing is a defect.
+
+### 3. Type scale
+- A fixed, named ramp (e.g. xs/sm/base/lg/xl/2xl). No arbitrary font-sizes.
+- Line-height ≥ 1.4 for body. One primary font family + a fallback stack.
+
+### 4. Accessibility — WCAG 2.1 AA (non-negotiable)
+- Text contrast ≥ **4.5:1** (≥ 3:1 for large text ≥ 24px / 19px-bold + UI/icon).
+- Every interactive element: keyboard-reachable, visible focus ring, ≥ 44×44px hit area.
+- Semantic HTML (`button`/`nav`/`main`/`label`), not `div` soup. Inputs have labels.
+- Images have `alt`; icon-only buttons have `aria-label`.
+- Color is never the ONLY signal (add text/icon for state).
+
+### 5. Component inventory — reuse, don't reinvent
+- Use an existing component before creating one. New component? it earns a place
+  in the inventory + the wireframe legend.
+- One component = one responsibility.
+
+### 6. State matrix — every interactive element covers all states
+- `default · hover · focus · active · disabled · loading · error · empty`.
+- Lists/data views handle: **empty**, **loading (skeleton)**, **error**, **partial**.
+- No dead-end empty states (always an action or explanation).
+
+### 7. Responsive breakpoints
+- Mobile-first. Honor the project breakpoints (XS < 640 · SM 640 · MD 768 ·
+  LG 1024 · XL 1280). Layout must not break or overflow between them.
+- No fixed widths that overflow small screens. Touch targets hold on mobile.
+
+### 8. Content & i18n
+- No hard-coded user-facing strings — go through the i18n layer.
+- Text can grow ~30% (translation) without breaking layout. Numbers/dates/currency
+  are locale-formatted.
+
+### 9. Feedback & motion
+- Every async action has visible feedback (spinner/skeleton/toast) within ~100ms.
+- Destructive actions confirm. Motion is subtle, respects `prefers-reduced-motion`.
+
+-----
+
+## RETURN FORMAT (the "ตรวจ" verdict)
+
+```
+UX CHECK: <screen/component>
+- wireframe match: PASS | DRIFT (<what left the frame>)
+- tokens/spacing/type: PASS | FAIL (<which raw values>)
+- a11y (WCAG AA): PASS | FAIL (<contrast/keyboard/semantic gap>)
+- states covered: <list missing, or "all">
+- responsive: PASS | FAIL (<breakpoint that breaks>)
+- i18n: PASS | FAIL
+- VERDICT: PASS | BLOCK (frontend phase cannot close)
+```
+
+Sources behind these defaults: WCAG 2.1 AA, Material Design 3 (semantic tokens),
+Apple HIG, Shopify Polaris. See `docs/research/design-ux-cookbook-wireframe-pattern.md`.

package/template/.claude/skills/ux-design/wireframe-template.md

@@ -0,0 +1,95 @@
+# Wireframe baseline — canonical prototype frame
+
+The low-fidelity reference every screen maps to BEFORE pixels exist. Copy a block
+per screen, fill the `[...]`. The agent validates generated UI against this frame
+(METHODOLOGY hard rule 9). Anything the screen renders that this frame does not
+describe is **drift** — fix the UI or, if the frame is genuinely missing, update
+this file first (`log-decision`).
+
+Keep it low fidelity on purpose: boxes + intent, not styling. Styling lives in the
+design tokens / cookbook, not here.
+
+-----
+
+## Global frame (applies to all screens)
+
+```
++--------------------------------------------------+
+| [top bar: logo · primary nav · account ]         |  <- persistent
++--------------------------------------------------+
+| [breadcrumb / page title ]                        |
+|                                                   |
+|   [ MAIN CONTENT REGION ]                          |
+|                                                   |
++--------------------------------------------------+
+| [footer / status ]                                |
++--------------------------------------------------+
+```
+
+- Breakpoints: nav collapses to a menu below MD (768px). Content single-column
+  below SM (640px).
+- Every screen declares: its route, its primary action, its empty/loading/error
+  rendering.
+
+-----
+
+## Screen template (copy per screen)
+
+```
+### Screen: [name]
+- Route:            [/path]
+- Goal (one line):  [what the user accomplishes here]
+- Primary action:   [the single most important button/intent]
+- Entry points:     [how the user arrives]
+- Exit / next:      [where they go after the primary action]
+
+Layout (regions, top -> bottom):
+  1. [region]   — [content + which components from the inventory]
+  2. [region]   — [...]
+  3. [region]   — [...]
+
+States:
+  - loading:  [skeleton of which regions]
+  - empty:    [message + the recovery action — never a dead end]
+  - error:    [message + retry]
+  - success:  [confirmation / what changes on screen]
+
+Data in / out:
+  - reads:    [endpoints from docs/ENDPOINTS.md]
+  - writes:   [endpoints]
+
+Responsive notes:
+  - mobile:   [what stacks / hides / becomes a sheet]
+  - desktop:  [what spreads out]
+
+A11y notes:
+  - focus order: [logical tab order]
+  - landmarks:   [main / nav / form labels]
+```
+
+-----
+
+## Component legend (the inventory the wireframe references)
+
+List every reusable block a screen may place. A screen MAY ONLY use components
+named here; a new one is added here first.
+
+```
+[Button]        — primary | secondary | ghost | destructive
+[Input]         — text | select | date | search   (always labelled)
+[Card]          — header + body + optional actions
+[Table/List]    — has empty + loading + error states baked in
+[Modal/Sheet]   — confirm | form ; sheet on mobile
+[Toast]         — success | error | info  (async feedback)
+[Nav]           — top bar (desktop) -> menu (mobile)
+[...add project components here...]
+```
+
+-----
+
+## How to use (agent)
+
+1. New screen -> write its block above from the PLAN acceptance spec.
+2. Build the screen to match the block (layout + states + data + a11y).
+3. Run the `ux-design` cookbook check. Verdict BLOCK -> fix before CLOSE.
+4. Frame too small for a real need -> update this file + `log-decision`, then build.