@wangs-ui/create-react-app 1.0.26-alpha.2

package/dist/bin.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+import path from "node:path";
+import process$1 from "node:process";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import readline from "node:readline/promises";
+//#region src/utils/fs.ts
+/**
+* Recursively copy a template directory into the target directory,
+* customizing project name and presets in text files.
+*/
+function copyProjectTemplate(options) {
+	const { srcDir, destDir, projectName, preset, ignore = [] } = options;
+	if (!fs.existsSync(srcDir)) return;
+	fs.mkdirSync(destDir, { recursive: true });
+	const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+	for (const entry of entries) {
+		if (ignore.includes(entry.name)) continue;
+		const srcPath = path.join(srcDir, entry.name);
+		let destName = entry.name;
+		if (destName === "_gitignore") destName = ".gitignore";
+		const destPath = path.join(destDir, destName);
+		if (entry.isDirectory()) copyProjectTemplate({
+			srcDir: srcPath,
+			destDir: destPath,
+			projectName,
+			preset,
+			ignore
+		});
+		else {
+			let content = fs.readFileSync(srcPath, "utf8");
+			if (destName === "package.json") content = content.replace(/"name":\s*"[^"]*"/, `"name": "${projectName}"`);
+			else if (destName === "index.html") content = content.replace(/<title>.*<\/title>/, `<title>${projectName}</title>`);
+			if (preset === "globalsettings") content = content.replace(/presetFixedAsset/g, "presetGlobalSettings").replace(/fixedasset/g, "globalsettings");
+			fs.writeFileSync(destPath, content, "utf8");
+		}
+	}
+}
+//#endregion
+//#region src/utils/mcpInstaller.ts
+function copyDirRecursive(srcDir, destDir) {
+	if (!fs.existsSync(srcDir)) return;
+	fs.mkdirSync(destDir, { recursive: true });
+	const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const srcPath = path.join(srcDir, entry.name);
+		const destPath = path.join(destDir, entry.name);
+		if (entry.isDirectory()) copyDirRecursive(srcPath, destPath);
+		else fs.copyFileSync(srcPath, destPath);
+	}
+}
+function setupAgentConfigurations(options) {
+	const { targetDir, templateDir, agents } = options;
+	const configuredAgents = [];
+	const agentsTemplateDir = path.join(templateDir, "agents");
+	const agentsMdSrc = path.join(agentsTemplateDir, "AGENTS.md");
+	if (fs.existsSync(agentsMdSrc)) fs.copyFileSync(agentsMdSrc, path.join(targetDir, "AGENTS.md"));
+	if (agents.includes("claude")) {
+		const mcpSrc = path.join(agentsTemplateDir, "mcp.json");
+		const claudeMdSrc = path.join(agentsTemplateDir, "CLAUDE.md");
+		if (fs.existsSync(mcpSrc)) fs.copyFileSync(mcpSrc, path.join(targetDir, ".mcp.json"));
+		if (fs.existsSync(claudeMdSrc)) fs.copyFileSync(claudeMdSrc, path.join(targetDir, "CLAUDE.md"));
+		configuredAgents.push("Claude Code (.mcp.json, CLAUDE.md)");
+	}
+	if (agents.includes("opencode")) {
+		const opencodeSrc = path.join(agentsTemplateDir, "opencode.json");
+		const mcpSrc = path.join(agentsTemplateDir, "mcp.json");
+		if (fs.existsSync(opencodeSrc)) {
+			fs.copyFileSync(opencodeSrc, path.join(targetDir, "opencode.json"));
+			const dotOpencode = path.join(targetDir, ".opencode");
+			fs.mkdirSync(dotOpencode, { recursive: true });
+			fs.copyFileSync(opencodeSrc, path.join(dotOpencode, "mcp.json"));
+		}
+		if (fs.existsSync(mcpSrc) && !fs.existsSync(path.join(targetDir, ".mcp.json"))) fs.copyFileSync(mcpSrc, path.join(targetDir, ".mcp.json"));
+		configuredAgents.push("OpenCode (opencode.json, .opencode/mcp.json)");
+	}
+	if (agents.includes("kilo")) {
+		const kiloMcpSrc = path.join(agentsTemplateDir, "kilo.mcp.json");
+		if (fs.existsSync(kiloMcpSrc)) {
+			const dotKilo = path.join(targetDir, ".kilo");
+			fs.mkdirSync(dotKilo, { recursive: true });
+			fs.copyFileSync(kiloMcpSrc, path.join(dotKilo, "mcp.json"));
+			const dotVscode = path.join(targetDir, ".vscode");
+			fs.mkdirSync(dotVscode, { recursive: true });
+			fs.copyFileSync(kiloMcpSrc, path.join(dotVscode, "mcp.json"));
+		}
+		configuredAgents.push("Kilo (.kilo/mcp.json, .vscode/mcp.json)");
+	}
+	if (agents.includes("antigravity")) {
+		const agentsMcpSrc = path.join(agentsTemplateDir, "agents.mcp.json");
+		const skillsSrc = path.join(agentsTemplateDir, "skills");
+		const dotAgents = path.join(targetDir, ".agents");
+		fs.mkdirSync(dotAgents, { recursive: true });
+		if (fs.existsSync(agentsMcpSrc)) fs.copyFileSync(agentsMcpSrc, path.join(dotAgents, "mcp_config.json"));
+		if (fs.existsSync(skillsSrc)) copyDirRecursive(skillsSrc, path.join(dotAgents, "skills"));
+		configuredAgents.push("Antigravity IDE & CLI (.agents/mcp_config.json, .agents/skills)");
+	}
+	return configuredAgents;
+}
+//#endregion
+//#region src/utils/packageManager.ts
+function detectPackageManager() {
+	const userAgent = process.env.npm_config_user_agent;
+	if (userAgent) {
+		if (userAgent.startsWith("pnpm")) return "pnpm";
+		if (userAgent.startsWith("bun")) return "bun";
+		if (userAgent.startsWith("yarn")) return "yarn";
+		if (userAgent.startsWith("npm")) return "npm";
+	}
+	return "pnpm";
+}
+function getInstallCommand(pm) {
+	switch (pm) {
+		case "pnpm": return "pnpm install";
+		case "bun": return "bun install";
+		case "yarn": return "yarn";
+		default: return "npm install";
+	}
+}
+function getRunCommand(pm, script) {
+	switch (pm) {
+		case "pnpm": return `pnpm ${script}`;
+		case "bun": return `bun ${script}`;
+		case "yarn": return `yarn ${script}`;
+		default: return `npm run ${script}`;
+	}
+}
+//#endregion
+//#region src/index.ts
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+function generateProject(options) {
+	const { projectName, targetDir, preset, agents } = options;
+	let templateDir = path.resolve(__dirname, "../template");
+	if (!fs.existsSync(templateDir)) templateDir = path.resolve(__dirname, "template");
+	console.log(`\n\x1b[36m🚀 Scaffolding Wangs UI React Application in \x1b[1m${targetDir}\x1b[0m...`);
+	copyProjectTemplate({
+		srcDir: templateDir,
+		destDir: targetDir,
+		projectName,
+		preset,
+		ignore: [
+			"agents",
+			"node_modules",
+			"dist"
+		]
+	});
+	let configuredAgents = [];
+	if (agents.length > 0) configuredAgents = setupAgentConfigurations({
+		targetDir,
+		templateDir,
+		agents
+	});
+	const pm = detectPackageManager();
+	const installCmd = getInstallCommand(pm);
+	const devCmd = getRunCommand(pm, "dev");
+	const lintCmd = getRunCommand(pm, "lint");
+	console.log("\n\x1B[32m✨ Project created successfully!\x1B[0m\n");
+	if (configuredAgents.length > 0) {
+		console.log("\x1B[1m🤖 AI Agent MCP & Skills Configured:\x1B[0m");
+		for (const agent of configuredAgents) console.log(`   \x1b[32m✔\x1b[0m ${agent}`);
+		console.log();
+	}
+	console.log("\x1B[1mNext steps:\x1B[0m");
+	if (!(targetDir === process.cwd())) {
+		const relPath = path.relative(process.cwd(), targetDir);
+		console.log(`  \x1b[36mcd\x1b[0m ${relPath}`);
+	}
+	console.log(`  \x1b[36m${installCmd}\x1b[0m`);
+	console.log(`  \x1b[36m${devCmd}\x1b[0m`);
+	console.log(`  \x1b[36m${lintCmd}\x1b[0m  \x1b[2m(runs Oxlint)\x1b[0m\n`);
+}
+//#endregion
+//#region src/prompts.ts
+async function promptUser(initialOptions) {
+	const rl = readline.createInterface({
+		input: process$1.stdin,
+		output: process$1.stdout
+	});
+	try {
+		let { projectName, preset, agents } = initialOptions;
+		if (!projectName) projectName = (await rl.question("\x1B[36m?\x1B[0m \x1B[1mProject name:\x1B[0m (\x1B[2mmy-wangs-app\x1B[0m) ")).trim() || "my-wangs-app";
+		if (!preset) if (initialOptions.yes) preset = "fixedasset";
+		else {
+			console.log("\n\x1B[1mSelect a Wangs UI Design Preset:\x1B[0m");
+			console.log("  \x1B[32m1)\x1B[0m fixedasset \x1B[2m(Recommended - Standard Theme)\x1B[0m");
+			console.log("  \x1B[32m2)\x1B[0m globalsettings \x1B[2m(Global Settings Theme)\x1B[0m");
+			preset = (await rl.question("\x1B[36m?\x1B[0m \x1B[1mEnter choice [1-2]:\x1B[0m (1) ")).trim() === "2" ? "globalsettings" : "fixedasset";
+		}
+		if (!agents) if (initialOptions.yes) agents = [
+			"kilo",
+			"opencode",
+			"claude",
+			"antigravity"
+		];
+		else {
+			console.log("\n\x1B[1mAI Agent & MCP Tooling Setup:\x1B[0m");
+			console.log("  \x1B[32m1)\x1B[0m All Supported Agents \x1B[2m(Kilo, OpenCode, Claude Code, Antigravity)\x1B[0m");
+			console.log("  \x1B[32m2)\x1B[0m Kilo only");
+			console.log("  \x1B[32m3)\x1B[0m OpenCode only");
+			console.log("  \x1B[32m4)\x1B[0m Claude Code only");
+			console.log("  \x1B[32m5)\x1B[0m Antigravity IDE & CLI only");
+			console.log("  \x1B[32m6)\x1B[0m Skip Agent Setup");
+			switch ((await rl.question("\x1B[36m?\x1B[0m \x1B[1mEnter choice [1-6]:\x1B[0m (1) ")).trim()) {
+				case "2":
+					agents = ["kilo"];
+					break;
+				case "3":
+					agents = ["opencode"];
+					break;
+				case "4":
+					agents = ["claude"];
+					break;
+				case "5":
+					agents = ["antigravity"];
+					break;
+				case "6":
+					agents = [];
+					break;
+				default:
+					agents = [
+						"kilo",
+						"opencode",
+						"claude",
+						"antigravity"
+					];
+					break;
+			}
+		}
+		return {
+			projectName,
+			preset,
+			agents
+		};
+	} finally {
+		rl.close();
+	}
+}
+//#endregion
+//#region bin.ts
+async function main() {
+	const args = process$1.argv.slice(2);
+	const options = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "-y" || arg === "--yes") options.yes = true;
+		else if (arg.startsWith("--preset=")) {
+			const val = arg.split("=")[1];
+			if (val === "fixedasset" || val === "globalsettings") options.preset = val;
+		} else if (arg === "--preset" && args[i + 1]) {
+			const val = args[++i];
+			if (val === "fixedasset" || val === "globalsettings") options.preset = val;
+		} else if (arg.startsWith("--agent=") || arg.startsWith("--agents=")) {
+			const val = arg.split("=")[1];
+			if (val === "all") options.agents = [
+				"kilo",
+				"opencode",
+				"claude",
+				"antigravity"
+			];
+			else if (val === "none") options.agents = [];
+			else options.agents = val.split(",").filter((a) => [
+				"kilo",
+				"opencode",
+				"claude",
+				"antigravity"
+			].includes(a));
+		} else if ((arg === "--agent" || arg === "--agents") && args[i + 1]) {
+			const val = args[++i];
+			if (val === "all") options.agents = [
+				"kilo",
+				"opencode",
+				"claude",
+				"antigravity"
+			];
+			else if (val === "none") options.agents = [];
+			else options.agents = val.split(",").filter((a) => [
+				"kilo",
+				"opencode",
+				"claude",
+				"antigravity"
+			].includes(a));
+		} else if (!arg.startsWith("-") && !options.projectName) options.projectName = arg;
+	}
+	const { projectName, preset, agents } = await promptUser(options);
+	const targetDir = path.resolve(process$1.cwd(), projectName);
+	generateProject({
+		projectName: path.basename(targetDir),
+		targetDir,
+		preset,
+		agents
+	});
+}
+try {
+	await main();
+} catch (err) {
+	console.error("\x1B[31mError during project creation:\x1B[0m", err);
+	process$1.exit(1);
+}
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@wangs-ui/create-react-app",
+  "version": "1.0.26-alpha.2",
+  "description": "Scaffold a modern React app with Wangs UI, Vite 8, Oxlint, Oxfmt, and AI Agent MCP integration",
+  "keywords": [
+    "antigravity",
+    "claude-code",
+    "create-react-app",
+    "kilo",
+    "mcp",
+    "opencode",
+    "oxfmt",
+    "oxlint",
+    "react",
+    "vite",
+    "wangs-ui"
+  ],
+  "homepage": "https://github.com/fewangsit/wangs-ui-react",
+  "license": "MIT",
+  "author": "Wangsit FE Developer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fewangsit/wangs-ui-react.git",
+    "directory": "packages/create-react-app"
+  },
+  "bin": {
+    "create-react-app": "./dist/bin.js",
+    "create-wangs-app": "./dist/bin.js",
+    "create-wangs-ui-react-app": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "template/index.html",
+    "template/package.json",
+    "template/oxfmt.config.ts",
+    "template/oxlint.config.ts",
+    "template/tsconfig.json",
+    "template/tsconfig.app.json",
+    "template/tsconfig.node.json",
+    "template/vite.config.ts",
+    "template/_gitignore",
+    "template/.npmrc",
+    "template/src",
+    "template/agents"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "scripts": {
+    "build": "vite build",
+    "check:publint": "publint",
+    "check:attw": "attw --pack ."
+  }
+}

package/template/_gitignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/mcp.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/template/agents/AGENTS.md

@@ -0,0 +1,49 @@
+# AI Agent Instructions for Wangs UI
+
+This application is built with **Wangs UI** (`@wangs-ui/react-core`, `@wangs-ui/react-icons`, `@wangs-ui/react-presets`, `@wangs-ui/react-i18n`, `@wangs-ui/form`), Tailwind CSS v4, and Vite 8.
+
+---
+
+## 1. Core Principles & Strict Rules
+
+1. **Primitive Component Rule (Mandatory)**:
+   - Always use components from `@wangs-ui/react-core` (`Button`, `Card`, `Dialog`, `Modal`, `Form`, `Field`, `InputText`, `Select`, `DataTable`, etc.).
+   - Do NOT write unstyled raw HTML controls (`<button>`, `<input>`, `<select>`, `<form>`).
+
+2. **Internationalization (`@wangs-ui/react-i18n`)**:
+   - All text visible to users MUST be wrapped in `t()` from `useI18n()`.
+   - Never hardcode raw string literals inside JSX components.
+   - For formatting dates, times, currencies, or numbers, use `useLocaleFormatter()`:
+     ```tsx
+     import { useI18n, useLocaleFormatter } from '@wangs-ui/react-i18n';
+
+     const { t } = useI18n();
+     const { formatDate, formatCurrency } = useLocaleFormatter();
+     ```
+
+3. **Typography & Styling Tokens**:
+   - Typeface: **Manrope** (geometric sans-serif).
+   - Use semantic heading classes (`.heading-1` to `.heading-6`, `.p`) for typography hierarchy.
+   - Use predefined color and spacing tokens (`bg-primary-500`, `text-secondary-900`, `gap-md`, `p-l`, `rounded-m`).
+
+4. **MCP Component Inspection**:
+   - The `@wangs-ui/mcp` server is configured in this workspace.
+   - Query the MCP server (`get-documentation`, `list-all-documentation`) to inspect component schemas, props, and design specifications before writing components.
+
+---
+
+## 2. Specialized Skills Reference
+
+When performing specific tasks, consult the detailed skill files in `.agents/skills/`:
+
+- **`i18n-standardization`** (`.agents/skills/i18n-standardization/SKILL.md`): Rules for JIT translation, named variables `{count}`, ICU plurals, and locale formatters.
+- **`wangs-ui-components`** (`.agents/skills/wangs-ui-components/SKILL.md`): Component composition, iconography from `@wangs-ui/react-icons`, and token usage.
+- **`form-management`** (`.agents/skills/form-management/SKILL.md`): Form implementation, schema typing, and validation with `@wangs-ui/form`.
+
+---
+
+## 3. Code Quality & Toolchain
+
+- **Linter**: `oxlint` (run `pnpm lint`)
+- **Formatter**: `oxfmt` (run `pnpm format`)
+- **Type Checker**: TypeScript with `tsc -b` (run `pnpm build`)

package/template/agents/CLAUDE.md

@@ -0,0 +1,22 @@
+# Claude Code Project Guidelines
+
+This project uses **Wangs UI**, React 19, and Vite 8.
+
+## MCP Tools
+
+The `@wangs-ui/mcp` server is configured in `.mcp.json`. Use it to inspect Wangs UI component documentation and story specifications before implementing new views.
+
+## Development Commands
+
+- `pnpm dev`: Start local development server
+- `pnpm build`: Type check and build production bundle
+- `pnpm lint`: Run Oxlint linter
+- `pnpm format`: Run Oxfmt formatter
+
+## Key Coding Rules
+
+- Use `@wangs-ui/react-core` for all UI elements (do not use unstyled raw HTML inputs/buttons).
+- Use `@wangs-ui/react-icons` for iconography.
+- Wrap all UI strings in `t('...')` from `useI18n()`.
+- Use `useLocaleFormatter()` for date, number, and currency formatting.
+- See `AGENTS.md` and `.agents/skills/` for in-depth design system standards.

package/template/agents/agents.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wangs-ui": {
+      "command": "npx",
+      "args": ["-y", "@wangs-ui/mcp@latest"]
+    }
+  }
+}

package/template/agents/kilo.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wangs-ui": {
+      "command": "npx",
+      "args": ["-y", "@wangs-ui/mcp@latest"]
+    }
+  }
+}

package/template/agents/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "wangs-ui": {
+      "command": "npx",
+      "args": ["-y", "@wangs-ui/mcp@latest"]
+    }
+  }
+}

package/template/agents/opencode.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "wangs-ui": {
+      "type": "local",
+      "command": ["npx", "-y", "@wangs-ui/mcp@latest"]
+    }
+  }
+}

package/template/agents/skills/form-management/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: form-management
+description: Guidelines and best practices for creating, validating, and submitting forms using Wangs UI Form and Field components.
+---
+
+# Skill: Form Management & Validation Guidelines
+
+This skill defines the standards for form implementation with `@wangs-ui/form`, `useFormControl`, and `@wangs-ui/react-core` `Form` / `Field` components.
+
+---
+
+## 1. Core Architecture
+
+Wangs UI provides strongly typed form controllers:
+
+- `useFormControl({ type: 'json' })`: For standard JSON payload forms.
+- `useFormControl({ type: 'formdata' })`: For multipart forms (file uploads).
+
+---
+
+## 2. Standard Form Pattern
+
+```tsx
+import React, { useState } from 'react';
+import { Button, Card, Form, Field, InputText, InputPassword } from '@wangs-ui/react-core';
+import { useFormControl } from '@wangs-ui/form';
+import { useI18n } from '@wangs-ui/react-i18n';
+
+interface LoginFormValues {
+  email: string;
+  password: string;
+}
+
+export default function LoginForm(): React.ReactElement {
+  const { t } = useI18n();
+  const formControl = useFormControl<LoginFormValues>({ type: 'json' });
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (values: LoginFormValues) => {
+    setLoading(true);
+    try {
+      console.log('Submitted values:', values);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Card className="w-full max-w-md p-6">
+      <Form control={formControl} onSubmit={handleSubmit} className="flex flex-col gap-4">
+        <h2 className="heading-2">{t('Sign In')}</h2>
+
+        <Field<string>
+          name="email"
+          label={t('Email Address')}
+          required
+          rules={{
+            pattern: {
+              value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+              message: t('Invalid email address'),
+            },
+          }}
+        >
+          {(field) => (
+            <InputText {...field} placeholder={t('Enter your email')} value={field.value || ''} />
+          )}
+        </Field>
+
+        <Field<string> name="password" label={t('Password')} required>
+          {(field) => (
+            <InputPassword
+              {...field}
+              placeholder={t('Enter your password')}
+              value={field.value || ''}
+            />
+          )}
+        </Field>
+
+        <Button type="submit" label={t('Submit')} severity="primary" loading={loading} />
+      </Form>
+    </Card>
+  );
+}
+```
+
+---
+
+## 3. Mandatory Rules
+
+1. **Always Use `<Form>` and `<Field>`**:
+   Never use raw HTML `<form>` or uncontrolled `<input>`.
+2. **Translate Labels and Error Messages**:
+   Always wrap `label`, `placeholder`, and validation `message` in `t()`.
+3. **Strongly Typed Models**:
+   Define a TypeScript interface for form values and pass it to `useFormControl<Model>()`.

package/template/agents/skills/i18n-standardization/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: i18n-standardization
+description: Guidelines and rules for implementing and using the JIT i18n translation functions (t) and locale formatters in this Wangs UI project.
+---
+
+# Skill: JIT i18n Implementation & Usage Guidelines
+
+This skill defines the coding standards, rules, and best practices for writing translation strings and formatting dates/numbers using the JIT i18n system.
+
+---
+
+## 1. Core Principles
+
+The localization system uses a **Just-In-Time (JIT)** workflow. All user-facing English strings act directly as keys. The `t()` function resolves these keys against local memory, the network cache, or triggers a real-time background backend AI translation without blocking UI rendering.
+
+---
+
+## 2. Mandatory Rules
+
+### A. Translate at Consumer Level for `ReactNode` Props
+
+All user-facing text props in Wangs UI components (`label`, `placeholder`, `emptyMessage`, `header`, `tooltip`, etc.) are typed as `ReactNode`. Components render them as-is and **do NOT call `t()` internally**. Translation MUST be called at the consumer level:
+
+```tsx
+// DO
+const { t } = useI18n();
+
+<Button label={t('Save Changes')} />
+<Select placeholder={t('Select category...')} />
+<DataTable emptyMessage={t('No data available')} />
+
+// DO NOT: pass raw English strings without t()
+<Button label="Save Changes" />
+```
+
+### B. Named Variable Interpolation (Enforced)
+
+Always use descriptive named variables (`{count}`, `{userName}`, `{fileName}`) passed via an object argument. This provides necessary semantic context for AI translation engines:
+
+```tsx
+// DO
+t('Upload {count} files to {folderName}', { count: 5, folderName: 'Documents' });
+
+// DO NOT: use positional indices for multi-variable strings
+t('Upload {0} files to {1}', 5, 'Documents');
+```
+
+### C. ICU Pluralization & Zero-State (`=0`)
+
+Write ICU conditional plural/select structures directly inside the text keys. Always include `=0` branches to handle zero values within ICU syntax instead of creating separate JavaScript `if` or ternary branches:
+
+```tsx
+// DO
+t('{count, plural, =0 {No files uploaded} one {Uploaded 1 file} other {Uploaded {count} files}}', {
+  count,
+});
+
+// DO NOT: write manual JS conditionals for pluralization
+count === 0 ? t('No files') : t('{count} files', { count });
+```
+
+### D. Formatting Dates, Numbers & Currencies
+
+Always format dates, numbers, currencies, and relative time using `useLocaleFormatter()` **before** passing them into `t()`:
+
+```tsx
+import { useI18n, useLocaleFormatter } from '@wangs-ui/react-i18n';
+
+const { t } = useI18n();
+const { formatDate, formatRelativeTime, formatCurrency, formatNumber } = useLocaleFormatter();
+
+// Date formatting
+const dateLabel = t('Created on {date}', {
+  date: formatDate(new Date(), 'dd MMMM yyyy'),
+});
+
+// Relative time formatting
+const timeLabel = t('Updated {time}', {
+  time: formatRelativeTime(updatedAt),
+});
+
+// Currency formatting
+const priceText = formatCurrency(150000, 'IDR');
+```
+
+---
+
+## 3. Strict Prohibitions (MUST NOT)
+
+1. **NO Dynamic String Concatenation**:
+   Never use string concatenation or template literals inside `t()`:
+   ```tsx
+   // FORBIDDEN
+   t('Hello ' + user.name);
+   t(`Upload to ${folder}`);
+   ```
+2. **NO Hardcoded Strings in JSX**:
+   Never render raw text nodes without `t()`:
+   ```tsx
+   // FORBIDDEN
+   <h1>Dashboard Overview</h1>
+   ```
+3. **NO Static Translation JSON Files**:
+   Never create static `.json` dictionaries (e.g. `id.json`, `en.json`). Localization is completely dynamic via JIT translation.

package/template/agents/skills/wangs-ui-components/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: wangs-ui-components
+description: Guidelines and rules for using and composing Wangs UI Design System components and icons in this React application.
+---
+
+# Skill: Wangs UI Component Usage & Design System Standards
+
+This skill defines the rules for building user interfaces with `@wangs-ui/react-core`, `@wangs-ui/react-icons`, and `@wangs-ui/react-presets`.
+
+---
+
+## 1. Subpath Import Style (Mandatory)
+
+Components and providers are exported via clean, modular subpaths:
+
+```tsx
+// Provider / Contexts
+import { WangsUiProvider } from '@wangs-ui/react-core/api';
+
+// Primitive Components
+import Button from '@wangs-ui/react-core/primitive/button';
+import Card from '@wangs-ui/react-core/primitive/card';
+import InputText from '@wangs-ui/react-core/primitive/inputtext';
+import Select from '@wangs-ui/react-core/primitive/select';
+import Dialog from '@wangs-ui/react-core/primitive/dialog';
+import Modal from '@wangs-ui/react-core/primitive/modal';
+import DataTable from '@wangs-ui/react-core/primitive/datatable';
+
+// Icons
+import { AddLine, SearchLine, DeleteBin6Line } from '@wangs-ui/react-icons';
+```
+
+---
+
+## 2. Primitive Component Rule (Strictly Enforced)
+
+Never use unstyled raw HTML controls when a corresponding Wangs UI primitive component exists:
+
+| Raw HTML Control (Forbidden) | Wangs UI Component (Mandatory) | Subpath Import                                 |
+| :--------------------------- | :----------------------------- | :--------------------------------------------- |
+| `<button>`                   | `Button`                       | `@wangs-ui/react-core/primitive/button`        |
+| `<input type="text">`        | `InputText`                    | `@wangs-ui/react-core/primitive/inputtext`     |
+| `<input type="number">`      | `InputNumber`                  | `@wangs-ui/react-core/primitive/inputnumber`   |
+| `<input type="password">`    | `InputPassword`                | `@wangs-ui/react-core/primitive/inputpassword` |
+| `<input type="checkbox">`    | `Checkbox`                     | `@wangs-ui/react-core/primitive/checkbox`      |
+| `<select>` / dropdown        | `Select` / `Dropdown`          | `@wangs-ui/react-core/primitive/select`        |
+| `<dialog>` / modal           | `Dialog` / `Modal`             | `@wangs-ui/react-core/primitive/dialog`        |
+| `<table>`                    | `DataTable`                    | `@wangs-ui/react-core/primitive/datatable`     |
+| Container box                | `Card`                         | `@wangs-ui/react-core/primitive/card`          |
+
+---
+
+## 3. Typography & Spacing Scale
+
+### Typography (Typeface: Manrope)
+
+Use semantic heading classes rather than arbitrary text size utilities:
+
+- `.heading-1` (22px, 600 weight) — Page title
+- `.heading-2` (18px, 600 weight) — Section title
+- `.heading-3` (16px, 500 weight) — Card / Container header
+- `.heading-4` (14px, 500 weight) — Sub-headers / Field labels
+- `.heading-5` (12px, 600 weight) — Small titles
+- `.p` (12px, 500 weight) — Body text
+
+### Color Tokens
+
+- Primary: `bg-primary-500`, `text-primary-500`, `border-primary-500`
+- Secondary / Text: `text-secondary-900` (main text), `text-secondary-500` (muted/caption), `border-secondary-200`
+- Semantic: `success-500`, `danger-500`, `warning-500`, `info-500`
+
+### Spacing Tokens (4px Grid)
+
+- `gap-xs` (4px), `gap-s` (6px), `gap-md` (8px), `gap-m` (12px), `gap-l` (16px), `gap-xl` (20px), `gap-xxl` (24px)
+- `p-xs`, `p-s`, `p-md`, `p-m`, `p-l`, `p-xl`, `p-xxl`
+
+---
+
+## 4. MCP Component Inspection
+
+When creating new views or composing complex components:
+
+- Use the `@wangs-ui/mcp` server tools (`get-documentation`, `list-all-documentation`) to inspect component props, types, and story examples.
+- Do NOT guess prop names or event handlers.

package/template/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&display=swap"
+      rel="stylesheet"
+    />
+    <title>Wangs UI React App</title>
+  </head>
+
+  <body class="bg-secondary-50 text-secondary-900 min-h-screen antialiased">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/oxfmt.config.ts

@@ -0,0 +1,3 @@
+import { oxfmtConfig } from '@fewangsit/oxlint-config-react';
+
+export default oxfmtConfig;

package/template/oxlint.config.ts

@@ -0,0 +1,3 @@
+import { oxlintConfig } from '@fewangsit/oxlint-config-react';
+
+export default oxlintConfig;

package/template/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "wangs-ui-react-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "lint": "oxlint -c oxlint.config.ts",
+    "lint:fix": "oxlint -c oxlint.config.ts --fix",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check"
+  },
+  "dependencies": {
+    "@wangs-ui/react-core": "^1.0.26-alpha.2",
+    "@wangs-ui/react-i18n": "^1.0.26-alpha.2",
+    "@wangs-ui/react-icons": "^1.0.26-alpha.2",
+    "@wangs-ui/react-presets": "^1.0.26-alpha.2",
+    "clsx": "^2.1.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@fewangsit/oxlint-config-react": "^1.0.13",
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/node": "^25.9.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.4",
+    "oxfmt": "^0.60.0",
+    "oxlint": "^1.75.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  }
+}

package/template/src/App.tsx

@@ -0,0 +1,58 @@
+import Button from '@wangs-ui/react-core/primitive/button';
+import Card from '@wangs-ui/react-core/primitive/card';
+import { useI18n, useLocaleFormatter } from '@wangs-ui/react-i18n';
+import { AddLine, RefreshLine } from '@wangs-ui/react-icons';
+import React, { useState } from 'react';
+
+export default function App(): React.ReactElement {
+  const { t, locale, setLocale } = useI18n();
+  const { formatDate } = useLocaleFormatter();
+  const [count, setCount] = useState<number>(0);
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center p-6">
+      <Card className="flex w-full max-w-md flex-col gap-6 p-6 shadow-lg">
+        <div className="flex flex-col gap-1">
+          <h1 className="heading-1 text-secondary-900 font-semibold">{t('Welcome to Wangs UI')}</h1>
+          <p className="text-secondary-500 text-xs">
+            {t('Today is {0}', formatDate(new Date(), 'dd MMMM yyyy'))}
+          </p>
+        </div>
+
+        <div className="rounded-m border-secondary-200 bg-secondary-50 flex items-center justify-between border p-4">
+          <span className="text-secondary-700 text-sm font-medium">{t('Current count:')}</span>
+          <span className="text-primary-500 font-mono text-lg font-bold">{count}</span>
+        </div>
+
+        <div className="flex gap-3">
+          <Button
+            className="flex-1"
+            icon={<AddLine />}
+            label={t('Increment')}
+            severity="primary"
+            variant="filled"
+            onClick={() => setCount((c) => c + 1)}
+          />
+          <Button
+            icon={<RefreshLine />}
+            label={t('Reset')}
+            severity="secondary"
+            variant="outline"
+            onClick={() => setCount(0)}
+          />
+        </div>
+
+        <div className="border-secondary-200 text-secondary-400 flex items-center justify-between border-t pt-4 text-xs">
+          <span>{t('Language: {0}', locale.toUpperCase())}</span>
+          <button
+            type="button"
+            className="hover:text-primary-500 font-medium underline"
+            onClick={() => setLocale(locale === 'en' ? 'id' : 'en')}
+          >
+            {t('Switch to {0}', locale === 'en' ? 'Bahasa Indonesia' : 'English')}
+          </button>
+        </div>
+      </Card>
+    </div>
+  );
+}

package/template/src/index.css

@@ -0,0 +1,5 @@
+@import '@wangs-ui/react-presets/fixedasset/style.css';
+@import '@wangs-ui/react-presets/theme.css';
+@import '@wangs-ui/react-icons/style.css';
+
+@source "../node_modules/@wangs-ui/react-presets";

package/template/src/main.tsx

@@ -0,0 +1,19 @@
+import { WangsUiProvider } from '@wangs-ui/react-core/api';
+import { WangsUiI18nProvider } from '@wangs-ui/react-i18n';
+import presetFixedAsset from '@wangs-ui/react-presets/fixedasset';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+
+import App from './App';
+
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
+  <React.StrictMode>
+    <WangsUiI18nProvider defaultLocale="en">
+      <WangsUiProvider configOptions={{ preset: presetFixedAsset }}>
+        <App />
+      </WangsUiProvider>
+    </WangsUiI18nProvider>
+  </React.StrictMode>,
+);

package/template/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/tsconfig.app.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": false,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/template/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "files": [],
+  "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}

package/template/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": false,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts", "oxlint.config.ts", "oxfmt.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,8 @@
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});