Gwind skill module

Implement Vue 3 interfaces with GWind

Translate Figma designs into maintainable Vue 3 + TypeScript while preserving the consumer project's architecture. Distribution route: local source via gwind-system-ui CLI, tokens from gwind-v2.

References — load progressively

When	Read
Mapping Figma elements, checking component API	references/component-library.md
CLI action, adding components, migration	references/cli-workflow.md
Colors, typography, spacing, radius, motion	references/design-tokens.md
Creating any file, folder, route, module, composable	references/project-structure.md
Editing consumer code, Vue conventions, a11y, forms, states	references/frontend-rules-core.md
GRC screens, Indonesian labels, approval flows, dashboards	references/frontend-rules-grc.md
Before writing any token/color/spacing value	references/frontend-figma-inspection.md
Reviewing/fixing existing implementation vs Figma	references/frontend-audit-workflow.md
Form, table, audit templates	examples/

Distribution contract

• gwind-system-ui — CLI only; copies source into the consumer project.
• gwind-v2 — only GWind token/theme package.
• Import GWind components from generated local family barrels. No runtime GWind package.
• Never install, import, or reference @pegadaian/gwind-ui or @pegadaian/gwind-vue.
• reka-ui and similar registry deps are normal component deps, not alternate distribution routes.
• Existing private-package references = migration debt. Remove only after local imports + CSS are migrated and verification passes.

Audit mode

When the task is to review and fix an existing implementation (not build from scratch):

1. Re-run Figma Variable and CSS Export inspection (references/frontend-figma-inspection.md) for every component in scope — even if done before.
2. Follow the 5-phase workflow in references/frontend-audit-workflow.md.
3. Token check mandatory before any custom class or style.
4. Fix via props → custom styling → generated source edit. Never !important.
5. Produce audit summary report before closing.

Goal: minimal, targeted, token-correct changes — not a rewrite.

Environment readiness check — run first, every time

Mandatory before any implementation, audit, CLI action, or code change.

Step 1 — Package manager and project root

ls package-lock.json yarn.lock pnpm-lock.yaml bun.lockb 2>/dev/null
cat package.json | grep '"name"\|"workspaces"'
cat pnpm-workspace.yaml 2>/dev/null

In a monorepo, identify the consumer app workspace. All subsequent checks run from that root.

Step 2 — gwind-system-ui init

cat gwind.json 2>/dev/null || echo "NOT FOUND: gwind.json"
ls src/assets/gwind.css 2>/dev/null || echo "NOT FOUND: gwind.css"
grep "gwind" src/assets/main.css 2>/dev/null || echo "NOT FOUND: gwind import in main CSS"

Signal	Action
gwind.json found, paths match	Proceed
gwind.json found, paths stale	Report mismatch; re-run init only if in scope
gwind.json missing	Run init before any add
gwind.css missing	Restore from git or re-run init
gwind.css not imported	Add @import "./gwind.css" to main CSS

Step 3 — gwind-v2

grep '"gwind-v2"' package.json
ls node_modules/gwind-v2/package.json 2>/dev/null || echo "NOT INSTALLED"
cat node_modules/gwind-v2/package.json 2>/dev/null | grep '"version"'
ls node_modules/gwind-v2/dist/base.css node_modules/gwind-v2/base.css 2>/dev/null || echo "CSS entry NOT FOUND"

Signal	Action
Listed + installed	Proceed
Listed, node_modules absent	Run <pm> install
Not listed	Run <pm> add gwind-v2
CSS entry missing	Re-install; check dist/ structure

Step 4 — Base dependencies and utils.ts

for dep in "@fontsource/nunito-sans" "clsx" "tailwind-merge" "reka-ui"; do
  ls node_modules/$dep/package.json 2>/dev/null && echo "OK: $dep" || echo "MISSING: $dep"
done

UTILS=$(cat gwind.json 2>/dev/null | grep utilsPath | sed 's/.*"//;s/".*//' || echo "src/lib/utils.ts")
grep "latin-600\|latin-700\|latin-800\|gwindTwMerge\|omicron\|GWIND_FONT_CLASS\|!\[font-family" $UTILS 2>/dev/null \
  || echo "utils.ts not found or missing required content"

utils.ts must have: 3 font weight imports, gwindTwMerge with all 12 scale names, GWIND_FONT_CLASS='![font-family:var(--font-family-base)]'. See references/frontend-rules-core.md for canonical shape.

Step 5 — Project structure

ls src/
find src -maxdepth 3 -type d | sort
find src -name "*.routes.ts" -o -name "router/index.ts" 2>/dev/null | head -5
find src -name "*.store.ts" -o -name "use*.ts" 2>/dev/null | head -10

Record the layout. Conform all new files to it. If new project, apply standard from references/project-structure.md.

Step 6 — Generated components

cat gwind.json 2>/dev/null | grep "componentsPath"
ls $(cat gwind.json 2>/dev/null | grep componentsPath | sed 's/.*"//;s/".*//') 2>/dev/null \
  || echo "No generated components found"

Step 7 — Readiness report

Produce before doing anything else:

GWIND ENVIRONMENT READINESS — <project> (<date>)

Package manager:         pnpm / npm / yarn / bun
Consumer app root:       <path>

gwind-system-ui init:
  gwind.json:            ✅ / ❌   componentsPath: <value>
  gwind.css:             ✅ / ❌   imported in main CSS: ✅ / ❌

gwind-v2:
  Installed:             ✅ / ❌   Version: <x.x.x>   CSS entry: ✅ / ❌

Base deps:
  nunito-sans: ✅/❌  clsx: ✅/❌  tailwind-merge: ✅/❌  reka-ui: ✅/❌

utils.ts:
  Found: ✅/❌  latin-600: ✅/❌  latin-700: ✅/❌  latin-800: ✅/❌
  gwindTwMerge: ✅/❌  scale(12): ✅/❌  GWIND_FONT_CLASS(v4): ✅/❌

Generated components:    <list or "none">
Project structure:       <modules/ / pages/ / flat>  Router: <per-module / inline / none>

Issues: <N>
  - <issue>: <action>

Status: ✅ READY TO PROCEED  /  ⚠️ ISSUES MUST BE RESOLVED FIRST

Do not proceed until ✅ READY TO PROCEED or user explicitly acknowledges issues.

Step 8 — Resolve issues

In order: <pm> install → gwind-system-ui init → <pm> add gwind-v2 @fontsource/nunito-sans clsx tailwind-merge → add @import "./gwind.css" → fix utils.ts (see references/frontend-rules-core.md) → <pm> add reka-ui. Re-run Steps 2–6 to confirm clean before continuing.

---

CLI version — resolve before every operation

node scripts/resolve-latest.mjs gwind-system-ui

Output is a JSON array: { package, version, resolved, resolvedAt, error? }. Use version only when resolved: true. Pin the exact version — never use unbounded @latest. If all targets fail, use committed generated source and report unresolved.

Evidence order

1. Existing generated components, gwind.json, wrappers, and conventions in the consumer.
2. Exact generated files committed in the consumer.
3. Installed gwind-system-ui and gwind-v2 package contents.
4. This skill's bundled references.
5. Official npm metadata for current latest.
6. GWind repo at recorded commit.

Never guess an API, flag, registry entry, or token — mark unknown as Not documented.

Core workflow

1. Inspect — target and Figma

• Run Environment Readiness Check first. No Figma inspection, code, or CLI until ✅ READY.
• Read project-structure.md before creating any file or folder.
• Inspect package.json, lockfile, gwind.json, global CSS, config files, aliases, utils file, component directories.
• Search for forbidden private package references.
• Inspect git status. Preserve unrelated uncommitted work.
• Inspect Figma node, states, hierarchy, constraints, responsive behavior. Record uncertainty.
• Before mapping any value: run Figma inspection from references/frontend-figma-inspection.md — Variables panel, CSS export, consumer theme, token gaps. Do not begin implementation without this.

2. Reuse before adding

Priority: existing feature wrapper → existing generated GWind component → add via CLI → compose primitives → new component for documented gap only.

Import via the project's alias or family barrel (@/components/ui/button). Keep adjustments scoped, token-based, API-compatible.

3. Map and implement

• Map Figma elements to verified local components.
• Reproduce all required states: default, hover, focus-visible, active, disabled, loading, invalid, empty, success, error.
• Prefer semantic structure and props over visual-only wrappers.

4. Tokens before raw values

• Prefer semantic utilities: bg-primary, text-foreground, border-input, text-destructive.
• Every value must trace: Figma variable → GWind token → utility. Unresolvable chain = document gap + comment before using arbitrary.
• Never hardcode raw hex or px from Figma CSS export without resolution attempt.
• Preserve consumer theme overrides. Do not edit node_modules.

5. Responsive and accessible

• Mobile-first. Use actual consumer breakpoints.
• Stack narrow toolbars/forms; bound table overflow.
• Connect labels, captions, errors. Preserve keyboard behavior and focus-visible.
• Icon-only controls need accessible names. Decorative icons get aria-hidden.
• Use Reka-based primitives for composite interactions. Do not rebuild them.

6. Controlled changes

• apply_patch for manual edits. No unrelated refactors or upgrades.
• Before CLI: resolve latest, confirm root/version/command/overwrites.
• On 1.0.1+, let add resolve registryDependencies. Inspect diff after.
• Skipped files ≠ error. Review before using --overwrite.
• In audit mode: classify every gap before touching code — see references/frontend-audit-workflow.md.
• lib/portal missing after overlay family add = blocker. See references/component-library.md.
• After CLI: inspect every changed file. Install only missing deps.

7. Verify

Typecheck → lint → tests → build → visual comparison vs Figma at mobile, tablet, desktop.

Check: states, keyboard-only operation, focus, labels, overflow, contrast. Confirm no private package references remain after migration.

Definition of Done

• Implementation matches requested Figma scope and responsive states.
• Components from committed local CLI output or consumer wrappers only.
• Only gwind-system-ui and gwind-v2 in the distribution path.
• No private package import, dep, or stylesheet in migrated scope.
• All tokens from consumer or gwind-v2; gaps explicit.
• Interactive controls: keyboard-usable, labeled, focus-visible, correct states.
• CLI diff reviewed; user work intact; checks pass or blockers reported.