thomas-agentkit 0.4.2 → 0.5.2

package/README.md

@@ -72,6 +72,7 @@ Standardize install defaults with `agentkit.config.json`:
 {
   "preset": "next",
   "templateSet": "standard",
+  "designSystem": "linear",
   "aiTools": ["codex", "cursor", "claude"],
   "personalization": {
     "projectName": "Acme CRM",
@@ -109,6 +110,12 @@ List available presets:
 npx thomas-agentkit --list-presets
 ```
 
+List bundled design systems (source variants for `DESIGN-SYSTEM.md`):
+
+```bash
+npx thomas-agentkit --list-design-systems
+```
+
 ## Installed Files
 
 AgentKit copies these bundled files into the target project:
@@ -126,6 +133,8 @@ AgentKit copies these bundled files into the target project:
 
 When a preset is selected, AgentKit also installs `STACK.md` and adds a note in `AGENTS.md` telling agents to read it before changing stack-specific code.
 
+Bundled design system guidance is stored under `templates/design-systems/` in this repository (for example `linear.md`, `apple.md`). The CLI installs the chosen variant into `DESIGN-SYSTEM.md` in the target project; variant paths are not separate install targets.
+
 Existing files are skipped by default so local edits are preserved. Use `--force` when you intentionally want to refresh files from the bundled package version.
 
 New installs wrap generated template content in AgentKit managed block markers:
@@ -140,7 +149,7 @@ Generated content
 
 Interactive personalization only applies during `agentkit init` when files are created or overwritten. It does not write a config file, and `agentkit update` does not reapply personalized values.
 
-`agentkit.config.json` can set `preset`, `templateSet`, `aiTools`, and `personalization` defaults. `templateSet` may be `minimal`, `standard`, or `full`; `aiTools` may include `codex`, `cursor`, `claude`, and `copilot`. `agentkit update` only uses config `preset` and continues to update all managed bundled templates.
+`agentkit.config.json` can set `preset`, `templateSet`, `designSystem`, `aiTools`, and `personalization` defaults. `templateSet` may be `minimal`, `standard`, or `full`; `designSystem` selects which bundled design-system variant fills `DESIGN-SYSTEM.md` (`linear` or `apple`); `aiTools` may include `codex`, `cursor`, `claude`, and `copilot`. `agentkit update` uses config `preset` and `designSystem` and continues to update all managed bundled templates.
 
 ## Presets
 
@@ -155,10 +164,11 @@ Presets add stack-specific guidance without scaffolding framework app files.
 ## CLI Reference
 
 ```text
-agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--write-config] [--preset <name>]
-agentkit update [target] [--dry-run] [--preset <name>]
+agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--write-config] [--preset <name>] [--design-system <name>]
+agentkit update [target] [--dry-run] [--preset <name>] [--design-system <name>]
 agentkit --list
 agentkit --list-presets
+agentkit --list-design-systems
 agentkit --help
 agentkit --version
 ```
@@ -171,12 +181,14 @@ Options:
 - `-y, --yes`: accept defaults without prompts
 - `--write-config`: write resolved install defaults to `agentkit.config.json`
 - `--preset <name>`: install stack-specific guidance (`next`, `sveltekit`, `express`, `convex`, `fullstack`)
+- `--design-system <name>`: design system variant for `DESIGN-SYSTEM.md` (`linear`, `apple`)
 - `--list`: list bundled template files
 - `--list-presets`: list available presets
+- `--list-design-systems`: list available design systems
 - `-h, --help`: show help
 - `-v, --version`: show package version
 
-For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`.
+For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`. `--design-system <name>` refreshes the managed `DESIGN-SYSTEM.md` body from the matching bundled variant.
 
 ## Local Development
 

package/dist/cli.js

@@ -14,8 +14,13 @@ const validPresets = ["next", "sveltekit", "express", "convex", "fullstack"];
 const validProjectTypes = ["generic", ...validPresets];
 const validAiTools = ["codex", "cursor", "claude", "copilot"];
 const validTemplateSets = ["minimal", "standard", "full"];
+const validDesignSystems = ["linear", "apple"];
+const designSystemLabels = {
+    linear: "Linear-inspired",
+    apple: "Apple-inspired",
+};
 const configFileName = "agentkit.config.json";
-const configKeys = ["preset", "templateSet", "aiTools", "personalization"];
+const configKeys = ["preset", "templateSet", "aiTools", "designSystem", "personalization"];
 const personalizationKeys = [
     "projectName",
     "projectDescription",
@@ -107,23 +112,35 @@ async function readPackageVersion() {
     const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
     return packageJson.version ?? "0.0.0";
 }
-async function getTemplateFiles(dir = templatesDir, base = templatesDir) {
+async function collectInstallableTemplatePaths(dir, base) {
     const dirStat = await stat(dir);
     if (!dirStat.isDirectory()) {
         throw new Error(`Bundled templates directory not found: ${templatesDir}`);
     }
     const entries = await readdir(dir, { withFileTypes: true });
-    const files = await Promise.all(entries.map(async (entry) => {
+    const discovered = [];
+    for (const entry of entries) {
         const absolutePath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            return getTemplateFiles(absolutePath, base);
+            if (dir === templatesDir && entry.name === "design-systems") {
+                continue;
+            }
+            discovered.push(...(await collectInstallableTemplatePaths(absolutePath, base)));
+            continue;
         }
         if (!entry.isFile()) {
-            return [];
+            continue;
         }
-        return [path.relative(base, absolutePath).split(path.sep).join("/")];
-    }));
-    return files.flat().sort();
+        discovered.push(path.relative(base, absolutePath).split(path.sep).join("/"));
+    }
+    return discovered;
+}
+async function getTemplateFiles() {
+    const discovered = await collectInstallableTemplatePaths(templatesDir, templatesDir);
+    const withDesignSystem = discovered.includes("DESIGN-SYSTEM.md")
+        ? discovered
+        : [...discovered, "DESIGN-SYSTEM.md"];
+    return withDesignSystem.sort();
 }
 function isPresetName(value) {
     return validPresets.includes(value);
@@ -137,12 +154,32 @@ function isAiToolName(value) {
 function isTemplateSetName(value) {
     return validTemplateSets.includes(value);
 }
+function isDesignSystemName(value) {
+    return validDesignSystems.includes(value);
+}
 function formatPresetList() {
     return validPresets.join(", ");
 }
 function formatTemplateSetList() {
     return validTemplateSets.join(", ");
 }
+function formatDesignSystemList() {
+    return validDesignSystems.join(", ");
+}
+function resolveDesignSystem(name) {
+    const normalized = name.toLowerCase();
+    if (!isDesignSystemName(normalized)) {
+        throw new Error(`Unknown design system "${name}". Valid design systems: ${formatDesignSystemList()}.`);
+    }
+    return normalized;
+}
+function effectiveDesignSystem(name) {
+    const trimmed = name?.trim();
+    if (!trimmed) {
+        return "linear";
+    }
+    return resolveDesignSystem(trimmed);
+}
 function resolvePreset(preset) {
     if (!preset) {
         return undefined;
@@ -202,6 +239,12 @@ function parseConfig(rawConfig, configPath) {
             return aiTool;
         });
     }
+    if (rawConfig.designSystem !== undefined) {
+        if (typeof rawConfig.designSystem !== "string") {
+            throw new Error(`${configFileName} designSystem must be a string.`);
+        }
+        config.designSystem = resolveDesignSystem(rawConfig.designSystem);
+    }
     if (rawConfig.personalization !== undefined) {
         assertPlainObject(rawConfig.personalization, `${configFileName} personalization`);
         assertKnownKeys(rawConfig.personalization, personalizationKeys, `${configFileName} personalization`);
@@ -252,6 +295,7 @@ async function applyInitConfig(options, config) {
         return;
     }
     options.preset ??= config.preset;
+    options.designSystem ??= config.designSystem;
     options.personalization ??= config.personalization;
     options.templateSet ??= config.templateSet;
     options.aiTools ??= config.aiTools;
@@ -261,6 +305,7 @@ function applyUpdateConfig(options, config) {
         return;
     }
     options.preset ??= config.preset;
+    options.designSystem ??= config.designSystem;
 }
 export function resolveProjectPreset(projectType) {
     if (!projectType) {
@@ -328,6 +373,7 @@ function getResolvedConfig(options) {
     const config = {
         templateSet: options.templateSet ?? "full",
         aiTools: options.aiTools ?? [],
+        designSystem: effectiveDesignSystem(options.designSystem),
     };
     const preset = resolvePreset(options.preset);
     if (preset) {
@@ -532,8 +578,8 @@ async function promptForPersonalization(defaults) {
         stackSummary,
     };
 }
-async function buildInitTemplateContent(file, preset, personalization) {
-    const content = await buildTemplateContent(file, preset);
+async function buildInitTemplateContent(file, preset, personalization, designSystem) {
+    const content = await buildTemplateContent(file, preset, designSystem);
     return personalizeTemplateContent(file, content, personalization);
 }
 async function installTemplates(targetArg, options) {
@@ -544,6 +590,7 @@ async function installTemplates(targetArg, options) {
             ? getSelectedTemplateFiles(options.templateSet ?? "full", options.aiTools ?? [], allTemplateFiles)
             : allTemplateFiles);
     const preset = resolvePreset(options.preset);
+    const designSystem = effectiveDesignSystem(options.designSystem);
     const created = [];
     const skipped = [];
     if (!options.dryRun) {
@@ -572,14 +619,8 @@ async function installTemplates(targetArg, options) {
         created.push(file);
         if (!options.dryRun) {
             await mkdir(path.dirname(destination), { recursive: true });
-            if (preset && file === "AGENTS.md") {
-                const content = await buildInitTemplateContent(file, preset, options.personalization);
-                await writeFile(destination, wrapManagedBlock(file, content));
-            }
-            else {
-                const content = await buildInitTemplateContent(file, preset, options.personalization);
-                await writeFile(destination, wrapManagedBlock(file, content));
-            }
+            const content = await buildInitTemplateContent(file, preset, options.personalization, designSystem);
+            await writeFile(destination, wrapManagedBlock(file, content));
         }
     }
     if (preset) {
@@ -614,13 +655,18 @@ function replaceManagedBlock(file, existingContent, nextContent) {
     const replacement = wrapManagedBlock(file, nextContent).trimEnd();
     return `${existingContent.slice(0, startIndex)}${replacement}${existingContent.slice(afterEndIndex)}`;
 }
-async function buildTemplateContent(file, preset) {
+async function buildTemplateContent(file, preset, designSystem) {
     if (file === "STACK.md") {
         if (!preset) {
             throw new Error("STACK.md requires a preset.");
         }
         return getStackGuidance(preset);
     }
+    if (file === "DESIGN-SYSTEM.md") {
+        const source = path.join(templatesDir, "design-systems", `${designSystem}.md`);
+        const content = await readFile(source, "utf8");
+        return addStackReference(file, content, preset);
+    }
     const source = path.join(templatesDir, file);
     const content = await readFile(source, "utf8");
     return addStackReference(file, content, preset);
@@ -628,6 +674,7 @@ async function buildTemplateContent(file, preset) {
 async function updateTemplates(targetArg, options) {
     const targetDir = path.resolve(process.cwd(), targetArg || ".");
     const preset = resolvePreset(options.preset);
+    const designSystem = effectiveDesignSystem(options.designSystem);
     const files = preset ? [...(await getTemplateFiles()), "STACK.md"] : await getTemplateFiles();
     const created = [];
     const updated = [];
@@ -636,7 +683,7 @@ async function updateTemplates(targetArg, options) {
     const unchanged = [];
     for (const file of files) {
         const destination = path.join(targetDir, file);
-        const nextContent = await buildTemplateContent(file, preset);
+        const nextContent = await buildTemplateContent(file, preset, designSystem);
         const destinationExists = await exists(destination);
         if (!destinationExists) {
             created.push(file);
@@ -777,6 +824,17 @@ async function resolveInteractiveTarget(target, options) {
     options.templateSet = templateSetResponse;
     options.aiTools = aiToolResponse;
     options.files = getSelectedTemplateFiles(templateSetResponse, aiToolResponse, templateFiles);
+    if (templateSetResponse === "standard" || templateSetResponse === "full") {
+        const designSystemResponse = await select({
+            message: "Which design system guidance?",
+            initialValue: effectiveDesignSystem(options.designSystem),
+            options: validDesignSystems.map((value) => ({ label: designSystemLabels[value], value })),
+        });
+        if (isCancel(designSystemResponse)) {
+            process.exit(130);
+        }
+        options.designSystem = designSystemResponse;
+    }
     if (!options.force) {
         const preset = resolvePreset(options.preset);
         const installFiles = preset ? [...options.files, "STACK.md"] : options.files;
@@ -819,6 +877,12 @@ async function main() {
         }
         return;
     }
+    if (process.argv.slice(2).includes("--list-design-systems")) {
+        for (const designSystem of validDesignSystems) {
+            console.log(designSystem);
+        }
+        return;
+    }
     const program = new Command();
     program
         .name("agentkit")
@@ -826,6 +890,7 @@ async function main() {
         .version(await readPackageVersion(), "-v, --version")
         .option("--list", "list bundled template files")
         .option("--list-presets", "list available presets")
+        .option("--list-design-systems", "list available design systems")
         .addHelpText("after", `
 
 Examples:
@@ -834,6 +899,7 @@ Examples:
   agentkit init --preset next
   agentkit init ./my-project --yes --dry-run
   agentkit --list-presets
+  agentkit --list-design-systems
   agentkit --list`);
     program
         .command("init")
@@ -845,6 +911,7 @@ Examples:
         .option("-y, --yes", "accept defaults for non-interactive runs")
         .option("--write-config", "write resolved install defaults to agentkit.config.json")
         .option("--preset <name>", `install stack-specific guidance (${formatPresetList()})`)
+        .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
         await applyInitConfig(options, await loadConfigForTarget(target));
         const resolvedTarget = await resolveInteractiveTarget(target, options);
@@ -857,6 +924,7 @@ Examples:
         .argument("[target]", "target project directory", ".")
         .option("--dry-run", "print planned changes without writing files")
         .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
+        .option("--design-system <name>", `design system guidance for DESIGN-SYSTEM.md (${formatDesignSystemList()})`)
         .action(async (target, options) => {
         applyUpdateConfig(options, await loadConfigForTarget(target));
         const result = await updateTemplates(target, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.4.2",
+  "version": "0.5.2",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
   "repository": {

package/templates/design-systems/apple.md

@@ -0,0 +1,236 @@
+# [Project Name] Design System - Apple-Inspired Foundations
+
+This design system codifies the visual and interaction principles for [Project Name].
+
+It is the default source of truth for app shell layout, navigation, lists, controls, and page chrome in this repository.
+
+All colors, typography families, and radii must be consumed through semantic tokens in `[theme stylesheet path, e.g. src/styles.css]` or a dedicated theme stylesheet imported there. Components must not hardcode literal color values or font family names.
+
+## 1) Surface And Color
+
+### Philosophy
+
+The interface reads as a calm, spacious canvas. Separation comes from spacing, typography, subtle grouped inset surfaces when grouping controls, and structural seams—not stacked decorative containers.
+
+### Token Roles
+
+Define semantic CSS custom properties and map them to the project's theme tokens:
+
+- `--background`: app canvas
+- `--foreground`: primary text
+- `--muted-foreground`: secondary/meta text
+- `--border`: structural seams
+- `--card`: grouped inset surfaces (forms, settings groups, grouped lists) and dialogs/popovers
+- `--popover`: overlay surfaces
+- `--accent`: subtle hover/active in content areas
+- `--sidebar`: sidebar canvas
+- `--sidebar-accent`: hover/active in sidebar
+- `--primary`: brand and primary CTA (system blue)
+- `--destructive`: danger actions
+- `--ring`: focus ring
+
+### Rules
+
+- Canvas-first for browsing and routine reading; use grouped inset surfaces only where controls belong together (forms, settings, grouped lists).
+- No decorative gradients on product surfaces.
+- Use one accent color, `--primary`, for brand and primary actions. Map `--primary` to system blue (for example `#007AFF` in light, `#0A84FF` in dark), expressed via tokens—not literals in components.
+- Prefer spacing and typographic hierarchy over extra backgrounds.
+- Keep all colors tokenized and theme-ready for light and dark modes.
+
+## 2) Typography
+
+### Families
+
+- Interface text: `font-sans` backed by `--font-sans` (map theme to `-apple-system, BlinkMacSystemFont, "SF Pro Text", "Inter", system-ui, sans-serif`).
+- Code, IDs, and timestamps: `font-mono` backed by `--font-mono` (map theme to `"SF Mono", ui-monospace, "JetBrains Mono", monospace`).
+
+Do not reference literal font families in component files.
+
+### Scale
+
+- Page heading: `text-2xl`, `font-semibold`
+- Section heading: `text-lg`, `font-semibold`
+- Body / row label: `text-sm`, `font-normal` to `font-medium`
+- Meta / secondary: `text-xs`, `font-normal`
+- Nav section label: `text-xs uppercase tracking-wide`, `font-medium`
+- Tiny helper: `text-[11px]`, `font-normal`
+
+### Rules
+
+- Headlines are clear and restrained; prefer slightly tighter tracking on large display sizes (`tracking-tight` where appropriate).
+- Use comfortable line height for body (`leading-normal` or `leading-relaxed`).
+- Reserve uppercase for nav section labels and compact metadata.
+
+## 3) Navigation
+
+### Structure
+
+1. Header row: identity, search, and create action.
+2. Primary links.
+3. Collapsible grouped links.
+4. Lightweight footer affordance for help or docs.
+
+### Item Styling
+
+- Default: `text-sm`, muted foreground.
+- Hover: subtle `sidebar-accent` background.
+- Active: full-width rounded rectangle, medium weight.
+- Icon size: 14px to 16px.
+- Nav row baseline: `rounded-lg h-9 px-3`.
+
+### Collapse Behavior
+
+- Expanded width: `15rem` or 240px.
+- Collapsed width: `3rem` or 48px, icon-only with tooltip.
+- Mobile: sheet/drawer using expanded width.
+- Keyboard shortcut: support the project's standard sidebar toggle shortcut, e.g. `Cmd+B`.
+
+## 4) Layout Regions
+
+### App Shell
+
+- Sidebar: fixed left, full viewport height, right seam border.
+- Content: `flex-1 min-w-0`, same background canvas.
+- Optional inspector: right panel, `22rem` to `28rem`, collapsible.
+
+### Common Page Patterns
+
+- List workspace: toolbar plus scrollable list.
+- Detail view: breadcrumbs/title plus body and optional inspector.
+- Editor split: left rail plus center editor.
+- Settings split: nav plus forms inside grouped inset surfaces.
+
+### Toolbar Strip
+
+- Height: `h-12`.
+- Bottom seam: `border-b border-border/50`.
+- No separate heavy background block.
+
+### Page padding
+
+- Content padding: `p-4` to `p-6` (16px to 24px) for comfortable reading rhythm.
+
+## 5) Interactive Elements
+
+### Buttons
+
+- Primary: solid `primary` (system blue).
+- Secondary: neutral fill.
+- Ghost: transparent with subtle hover fill.
+- Destructive: `destructive` only for dangerous confirms.
+- Icon-only: `size-9` or `size-10`, ghost, tooltip.
+
+Rules:
+
+- Default radius: `rounded-lg` using the tokenized radius scale.
+- Sparse shadows; prefer borders for separation on web.
+- Primary buttons are intentional—do not pepper every row with a primary.
+
+### Inputs
+
+- Default height: `h-9`; relaxed contexts: `h-10` to `h-12`.
+- Tokenized input background and border.
+- Visible focus ring: `ring-2 ring-ring` with comfortable offset.
+- Labels above fields. Do not use floating labels by default.
+
+### Menus / Popovers / Dialogs
+
+- Tokenized `popover` surface and subtle border.
+- Typography: `text-sm` for menus; `text-sm` to `text-base` for dialogs as needed.
+- Comfortable spacing.
+- Dialog actions align right: secondary then primary.
+
+## 6) Lists And Data
+
+### Row Anatomy
+
+- Relaxed, single-line by default where possible.
+- Hover uses subtle accent fill.
+- Selected row uses tinted fill derived from `--primary` (for example ~12% opacity in light, ~24% in dark) plus medium weight.
+- Avoid per-row borders; separate by spacing and padding rhythm.
+
+### Grouping And Tables
+
+- Group labels are muted; children are indented or wrapped in grouped inset surfaces.
+- Table headers: compact meta style; avoid heavy uppercase unless it aids scanability.
+- No zebra striping or heavy gridlines.
+
+## 7) Status And Feedback
+
+- Status: small dots or SF-symbol-style glyphs with semantic meaning (optional).
+- Loading: skeletons for content, spinners only for inline actions.
+- Toasts: soft shadow, corner-pinned or non-intrusive, auto-dismiss.
+- Empty states: icon, short message, and optional single CTA.
+
+## 8) Motion
+
+- Motion confirms state changes; it is never decorative.
+- Micro interactions: about 200ms.
+- Layout shifts: about 300ms to 350ms.
+- Preferred easing: `cubic-bezier(0.25, 0.1, 0.25, 1)`.
+- Sheets and popovers may use a subtle spring-like overshoot when it aids affordance; keep amplitude low on web.
+- Respect `prefers-reduced-motion` with near-instant transitions.
+
+## 9) Spacing System
+
+Base unit is 4px, using the project's spacing scale.
+
+- `p-1` or 4px: tight internals.
+- `p-2` or 8px: compact section padding.
+- `p-3` or 12px: dense content blocks.
+- `p-4` or 16px: page-level rhythm.
+- `p-6` or 24px: relaxed sections when the layout calls for breathing room.
+
+Density guidelines:
+
+- Sidebar: relaxed, `h-9` rows.
+- Content: moderate, `h-10` to `h-12` rows.
+- Forms/settings: relaxed, `h-12` to `h-14` rows.
+
+## 10) Accessibility
+
+- Full keyboard navigation for all controls.
+- Consistent visible focus styles.
+- Semantic landmarks such as `nav` and `main`.
+- Collapsibles expose `aria-expanded`.
+- Ensure WCAG AA contrast in both themes.
+
+## 11) Anti-Patterns
+
+- Do not wrap routine browsing content in grouped inset surfaces.
+- Do not introduce multiple accent colors.
+- Do not add decorative gradients behind core product surfaces.
+- Do not stack multiple competing toolbars.
+- Do not color-code nav icons.
+- Do not use heavy drop shadows for everyday chrome.
+- Do not hardcode colors or font families in components.
+
+## 12) Applying This System
+
+### Where Values Live
+
+- Theme tokens and base layer: `[theme stylesheet path, e.g. src/styles.css]`.
+- App shell composition: `[route/layout path, e.g. src/routes or app]`.
+- Reusable UI primitives: `[components path, e.g. src/components/ui]`.
+
+### New Component Checklist
+
+1. Canvas-first or justified grouped inset for grouped controls—not card-first for everything?
+2. Uses 2-3 text hierarchy levels max?
+3. Has subtle hover and clear active states?
+4. Uses primary color only where needed?
+5. Uses spacing rhythm in 4px increments?
+6. Has complete keyboard and focus behavior?
+7. Uses token-driven colors and fonts?
+8. Works in light and dark themes?
+
+### For Coding Agents
+
+- Read this file before changing UI, layout, navigation, styling, or components.
+- Prefer existing UI primitives and local layout patterns.
+- Do not introduce new visual language without documenting the reason in the implementation brief or PR.
+- Before handoff, check responsive behavior, focus states, text overflow, loading states, empty states, and token usage.
+
+### Working Rule
+
+Default to these principles unless a deliberate exception is documented in a feature-specific spec.