@installagent/sdk 0.1.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.
Files changed (94) hide show
  1. package/dist/agent-templates.d.ts +90 -0
  2. package/dist/agent-templates.js +211 -0
  3. package/dist/client-build.d.ts +50 -0
  4. package/dist/client-build.js +155 -0
  5. package/dist/client-context.d.ts +40 -0
  6. package/dist/client-context.js +70 -0
  7. package/dist/client-drive.d.ts +67 -0
  8. package/dist/client-drive.js +278 -0
  9. package/dist/client-intake.d.ts +68 -0
  10. package/dist/client-intake.js +189 -0
  11. package/dist/client-linear.d.ts +30 -0
  12. package/dist/client-linear.js +85 -0
  13. package/dist/docs-search.d.ts +44 -0
  14. package/dist/docs-search.js +187 -0
  15. package/dist/doctor.d.ts +43 -0
  16. package/dist/doctor.js +425 -0
  17. package/dist/env-file.d.ts +25 -0
  18. package/dist/env-file.js +69 -0
  19. package/dist/env-fill.d.ts +43 -0
  20. package/dist/env-fill.js +161 -0
  21. package/dist/env-push.d.ts +37 -0
  22. package/dist/env-push.js +137 -0
  23. package/dist/env-registry.d.ts +49 -0
  24. package/dist/env-registry.js +230 -0
  25. package/dist/exec.d.ts +14 -0
  26. package/dist/exec.js +16 -0
  27. package/dist/fathom-webhook.d.ts +44 -0
  28. package/dist/fathom-webhook.js +123 -0
  29. package/dist/fs-utils.d.ts +9 -0
  30. package/dist/fs-utils.js +34 -0
  31. package/dist/gcp-service-account-key.d.ts +37 -0
  32. package/dist/gcp-service-account-key.js +66 -0
  33. package/dist/gemini-api-key.d.ts +47 -0
  34. package/dist/gemini-api-key.js +132 -0
  35. package/dist/git.d.ts +16 -0
  36. package/dist/git.js +29 -0
  37. package/dist/github-token.d.ts +24 -0
  38. package/dist/github-token.js +30 -0
  39. package/dist/index.d.ts +25 -0
  40. package/dist/index.js +28 -0
  41. package/dist/init.d.ts +47 -0
  42. package/dist/init.js +101 -0
  43. package/dist/linear-project.d.ts +81 -0
  44. package/dist/linear-project.js +192 -0
  45. package/dist/new-client.d.ts +32 -0
  46. package/dist/new-client.js +89 -0
  47. package/dist/ping.d.ts +6 -0
  48. package/dist/ping.js +7 -0
  49. package/dist/portal-admin.d.ts +133 -0
  50. package/dist/portal-admin.js +144 -0
  51. package/dist/sync-templates.d.ts +58 -0
  52. package/dist/sync-templates.js +109 -0
  53. package/dist/template-sync.d.ts +55 -0
  54. package/dist/template-sync.js +90 -0
  55. package/dist/templates.d.ts +19 -0
  56. package/dist/templates.js +24 -0
  57. package/dist/wizard.d.ts +78 -0
  58. package/dist/wizard.js +213 -0
  59. package/package.json +30 -0
  60. package/templates/env.example +60 -0
  61. package/templates/workspace-root/.claude/settings.json +39 -0
  62. package/templates/workspace-root/AGENT.md +205 -0
  63. package/templates/workspace-root/AGENTS.md +11 -0
  64. package/templates/workspace-root/CLAUDE.md +63 -0
  65. package/templates/workspace-root/GEMINI.md +24 -0
  66. package/templates/workspace-root/ONBOARDING.md +164 -0
  67. package/templates/workspace-root/README.md +67 -0
  68. package/templates/workspace-root/skills/CLAUDE.md +79 -0
  69. package/templates/workspace-root/skills/client-deliverables/SKILL.md +131 -0
  70. package/templates/workspace-root/skills/client-deliverables/references/package-layout.md +103 -0
  71. package/templates/workspace-root/skills/client-facing-docs/SKILL.md +131 -0
  72. package/templates/workspace-root/skills/client-facing-docs/references/doc-structures.md +81 -0
  73. package/templates/workspace-root/skills/client-llm-setup/SKILL.md +97 -0
  74. package/templates/workspace-root/skills/client-llm-setup/references/guide-template.md +87 -0
  75. package/templates/workspace-root/skills/client-workflow-diagram/SKILL.md +141 -0
  76. package/templates/workspace-root/skills/client-workflow-diagram/references/excalidraw-format.md +140 -0
  77. package/templates/workspace-root/skills/contract-tech-agnostic/SKILL.md +99 -0
  78. package/templates/workspace-root/skills/contract-tech-agnostic/references/Install_Agent_SOW_Template.docx +0 -0
  79. package/templates/workspace-root/skills/design-system/SKILL.md +118 -0
  80. package/templates/workspace-root/skills/design-system/references/tokens.md +139 -0
  81. package/templates/workspace-root/skills/engagement-spec/SKILL.md +272 -0
  82. package/templates/workspace-root/skills/engagement-spec/references/spec-templates.md +220 -0
  83. package/templates/workspace-root/skills/house-voice/SKILL.md +158 -0
  84. package/templates/workspace-root/skills/house-voice/references/source-copy.md +173 -0
  85. package/templates/workspace-root/skills/ia-cli/SKILL.md +87 -0
  86. package/templates/workspace-root/skills/installagent-brand-kit/SKILL.md +112 -0
  87. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-logo.svg +1 -0
  88. package/templates/workspace-root/skills/installagent-brand-kit/assets/installagent-mark.svg +1 -0
  89. package/templates/workspace-root/skills/installagent-brand-kit/references/brand-tokens.md +71 -0
  90. package/templates/workspace-root/skills/installagent-brand-kit/references/branded-pdf.md +66 -0
  91. package/templates/workspace-root/skills/installagent-brand-kit/references/excalidraw-red-theme.md +73 -0
  92. package/templates/workspace-root/skills/installagent-brand-kit/scripts/brand.py +175 -0
  93. package/templates/workspace-root/skills/linear/SKILL.md +186 -0
  94. package/templates/workspace-root/skills/tech-call-prep/SKILL.md +141 -0
@@ -0,0 +1,140 @@
1
+ # Excalidraw file format — quick reference
2
+
3
+ Enough of the `.excalidraw` JSON shape to hand-author or script a diagram. The
4
+ format is stable (`version: 2`). When in doubt, draw two boxes + an arrow at
5
+ excalidraw.com, "Save to…", and read the JSON.
6
+
7
+ ## Top-level shape
8
+
9
+ ```json
10
+ {
11
+ "type": "excalidraw",
12
+ "version": 2,
13
+ "source": "https://excalidraw.com",
14
+ "elements": [ /* every box, label, and arrow, in z-order */ ],
15
+ "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
16
+ "files": {}
17
+ }
18
+ ```
19
+
20
+ ## Element fields that matter
21
+
22
+ Every element needs these (Excalidraw fills sensible defaults for the rest, but
23
+ include them to be safe): `id` (unique string), `type`, `x`, `y`, `width`,
24
+ `height`, `angle` (0), `strokeColor`, `backgroundColor`, `fillStyle` ("solid"),
25
+ `strokeWidth` (2), `strokeStyle` ("solid"), `roughness` (1 hand-drawn, 0 clean),
26
+ `opacity` (100), `groupIds` ([]), `frameId` (null), `roundness` ({"type":3} for
27
+ rounded rectangles, else null), `seed` (any int), `version` (1), `versionNonce`
28
+ (any int), `isDeleted` (false), `boundElements` ([]), `updated` (epoch ms),
29
+ `link` (null), `locked` (false).
30
+
31
+ ### House palette (match the Kingdom diagrams)
32
+
33
+ | Use | strokeColor | backgroundColor |
34
+ |---|---|---|
35
+ | Stage container | `#364fc7` | `#dbe4ff` |
36
+ | Standard node | `#1e1e1e` | `#ffffff` or `#f8f9fa` |
37
+ | AI node (highlight) | `#5f3dc4` | `#eebefa` / `#f3d9fa` |
38
+ | Exception / alert | `#c92a2a` | `#ffc9c9` |
39
+ | Success / write | `#2b8a3e` | `#b2f2bb` |
40
+
41
+ Layout math that reads well: containers 260 wide, ~80px gap between columns;
42
+ node boxes ~220 wide × ~64 tall, ~24px vertical gap, inset ~20px from the
43
+ container edges.
44
+
45
+ ## Rectangle (a node or a stage container)
46
+
47
+ ```json
48
+ {
49
+ "id": "node-normalize",
50
+ "type": "rectangle",
51
+ "x": 360, "y": 140, "width": 220, "height": 64,
52
+ "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "#f8f9fa",
53
+ "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
54
+ "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null,
55
+ "roundness": { "type": 3 }, "seed": 12345, "version": 1,
56
+ "versionNonce": 11111, "isDeleted": false,
57
+ "boundElements": [{ "id": "label-normalize", "type": "text" }],
58
+ "updated": 1715000000000, "link": null, "locked": false
59
+ }
60
+ ```
61
+
62
+ ## Text (bind it to its box via `containerId`)
63
+
64
+ A label inside a box: give the text a `containerId` pointing at the rectangle's
65
+ `id`, and add the text's id to the rectangle's `boundElements`. Excalidraw then
66
+ centers and wraps it.
67
+
68
+ ```json
69
+ {
70
+ "id": "label-normalize",
71
+ "type": "text",
72
+ "x": 370, "y": 158, "width": 200, "height": 25,
73
+ "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent",
74
+ "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
75
+ "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null,
76
+ "roundness": null, "seed": 22222, "version": 1, "versionNonce": 22222,
77
+ "isDeleted": false, "boundElements": [], "updated": 1715000000000,
78
+ "link": null, "locked": false,
79
+ "text": "🔧 Normalize", "fontSize": 20, "fontFamily": 1,
80
+ "textAlign": "center", "verticalAlign": "middle",
81
+ "containerId": "node-normalize", "originalText": "🔧 Normalize",
82
+ "lineHeight": 1.25
83
+ }
84
+ ```
85
+
86
+ `fontFamily`: 1 = hand-drawn (Virgil), 2 = normal (Helvetica), 3 = code (Cascadia).
87
+
88
+ ## Arrow (bind endpoints so they follow the boxes)
89
+
90
+ ```json
91
+ {
92
+ "id": "arrow-1",
93
+ "type": "arrow",
94
+ "x": 300, "y": 172, "width": 60, "height": 0,
95
+ "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent",
96
+ "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
97
+ "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null,
98
+ "roundness": { "type": 2 }, "seed": 33333, "version": 1,
99
+ "versionNonce": 33333, "isDeleted": false, "boundElements": [],
100
+ "updated": 1715000000000, "link": null, "locked": false,
101
+ "points": [[0, 0], [60, 0]],
102
+ "startBinding": { "elementId": "node-source", "focus": 0, "gap": 8 },
103
+ "endBinding": { "elementId": "node-normalize", "focus": 0, "gap": 8 },
104
+ "startArrowhead": null, "endArrowhead": "arrow"
105
+ }
106
+ ```
107
+
108
+ `points` are relative to the arrow's `x`/`y`. Bindings make the arrow stick to
109
+ the boxes when they move; `gap` is the standoff distance.
110
+
111
+ ## Minimal whole-file example (source → normalize)
112
+
113
+ ```json
114
+ {
115
+ "type": "excalidraw", "version": 2, "source": "https://excalidraw.com",
116
+ "elements": [
117
+ { "id": "node-source", "type": "rectangle", "x": 40, "y": 140, "width": 220, "height": 64, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "#ffffff", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": { "type": 3 }, "seed": 1, "version": 1, "versionNonce": 1, "isDeleted": false, "boundElements": [{ "id": "label-source", "type": "text" }], "updated": 1715000000000, "link": null, "locked": false },
118
+ { "id": "label-source", "type": "text", "x": 50, "y": 158, "width": 200, "height": 25, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": null, "seed": 2, "version": 1, "versionNonce": 2, "isDeleted": false, "boundElements": [], "updated": 1715000000000, "link": null, "locked": false, "text": "📡 New transaction", "fontSize": 20, "fontFamily": 1, "textAlign": "center", "verticalAlign": "middle", "containerId": "node-source", "originalText": "📡 New transaction", "lineHeight": 1.25 },
119
+ { "id": "node-normalize", "type": "rectangle", "x": 360, "y": 140, "width": 220, "height": 64, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "#f8f9fa", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": { "type": 3 }, "seed": 3, "version": 1, "versionNonce": 3, "isDeleted": false, "boundElements": [{ "id": "label-normalize", "type": "text" }], "updated": 1715000000000, "link": null, "locked": false },
120
+ { "id": "label-normalize", "type": "text", "x": 370, "y": 158, "width": 200, "height": 25, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": null, "seed": 4, "version": 1, "versionNonce": 4, "isDeleted": false, "boundElements": [], "updated": 1715000000000, "link": null, "locked": false, "text": "🔧 Normalize", "fontSize": 20, "fontFamily": 1, "textAlign": "center", "verticalAlign": "middle", "containerId": "node-normalize", "originalText": "🔧 Normalize", "lineHeight": 1.25 },
121
+ { "id": "arrow-1", "type": "arrow", "x": 268, "y": 172, "width": 84, "height": 0, "angle": 0, "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid", "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": { "type": 2 }, "seed": 5, "version": 1, "versionNonce": 5, "isDeleted": false, "boundElements": [], "updated": 1715000000000, "link": null, "locked": false, "points": [[0, 0], [84, 0]], "startBinding": { "elementId": "node-source", "focus": 0, "gap": 8 }, "endBinding": { "elementId": "node-normalize", "focus": 0, "gap": 8 }, "startArrowhead": null, "endArrowhead": "arrow" }
122
+ ],
123
+ "appState": { "gridSize": null, "viewBackgroundColor": "#ffffff" },
124
+ "files": {}
125
+ }
126
+ ```
127
+
128
+ ## Scripted generation (preferred for big/maintained diagrams)
129
+
130
+ For anything beyond ~15 elements, generate the JSON instead of hand-editing.
131
+ Pattern (see `client-kingdom/diagrams/build-estimate-diagrams.py`):
132
+
133
+ 1. Define stages and nodes as plain data (lists/dicts).
134
+ 2. Loop: compute x/y per column and row; append a rectangle + a bound text per
135
+ node; append arrows from the flow edges.
136
+ 3. `json.dump` to a scratch path for the deck export (client repos no longer
137
+ commit `.excalidraw` — their diagrams are self-contained HTML in `docs/`).
138
+
139
+ Keeping the diagram as code means a scope change is a data edit + re-run, not an
140
+ hour of dragging boxes.
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: contract-tech-agnostic
3
+ description: Use whenever drafting, editing, or reviewing a client-facing contract, services agreement, master services agreement (MSA), statement of work (SOW), engagement letter, or proposal. Describe deliverables by FUNCTION and OUTCOME, not by implementation technology. Triggers on phrases like "draft a contract," "write an SOW," "services agreement," "MSA," "engagement letter," "client agreement," "proposal," "scope document," "redline this contract," or any time a legal/commercial document for a client audience is being produced. Do NOT use this for internal tech specs, runbooks, architecture docs, or kickoff/onboarding docs — those should name specific tools.
4
+ ---
5
+
6
+ # Tech-agnostic contract drafting
7
+
8
+ ## The rule
9
+
10
+ Contracts and SOWs describe **what** is being delivered (function, scope, outcome). They do **not** name **how** (the specific vendors, products, frameworks, or platforms used to deliver it). Implementation details belong in tech specs and onboarding docs, not in the legal agreement.
11
+
12
+ ## Why this matters
13
+
14
+ - **Tool swaps shouldn't require contract amendments.** If a contract says "n8n workflow," swapping to Make or a custom service mid-project legally requires an amendment. If it says "automated workflow," the operator has flexibility.
15
+ - **Vendors change.** They deprecate features, change pricing, alter terms, get acquired, or shut down. Naming a vendor in a contract creates an implicit dependency on that vendor's continued existence and behavior.
16
+ - **Client audiences care about outcomes.** Naming tools in a contract clutters the scope, signals immaturity, and can confuse non-technical signatories.
17
+ - **Third-party blame allocation gets murky.** When the contract names "Plaid" and Plaid has an outage, who's responsible? Easier to say "third-party bank-data providers" generically and handle in a force-majeure clause.
18
+ - **Negotiation friction.** Clients sometimes balk at named tools they have opinions about ("we already pay for X, why are you using Y?"). Functional language sidesteps it.
19
+
20
+ ## Substitution dictionary
21
+
22
+ Use these replacements as a starting point — adapt language to the engagement.
23
+
24
+ | Don't write in contracts | Do write |
25
+ |---|---|
26
+ | Plaid, Yodlee, Finicity, MX | "a secure bank-data aggregation service" / "a third-party bank-data provider" |
27
+ | QuickBooks, QBO, Xero, NetSuite, Sage | "the Client's accounting system" |
28
+ | n8n, Zapier, Make, Workato, custom workflow | "an automated workflow" / "Operator's automation platform" |
29
+ | Anthropic, Claude, OpenAI, GPT, Gemini, Llama | "an AI classification service" / "AI-assisted classification" |
30
+ | Slack, Microsoft Teams, Discord, Google Chat | "the Client's chat tool" / "an internal messaging channel" |
31
+ | Google Sheets, Airtable, Notion, Excel Online | "a shared-document tool" / "a collaborative spreadsheet" |
32
+ | Google Drive, Dropbox, Box, OneDrive | "a shared file-storage system" |
33
+ | AWS, GCP, Azure, DigitalOcean, Vercel, Heroku | "Operator's hosted infrastructure" / "a commercial cloud-hosting provider" |
34
+ | Postgres, MySQL, Mongo, Redis, DynamoDB | "a database" / "Operator's data store" |
35
+ | GitHub, GitLab, Bitbucket | "a source-code repository" |
36
+ | Linear, Asana, Jira, Trello, ClickUp | "a project-tracking tool" |
37
+ | Stripe, Square, PayPal, Adyen | "a payment processor" |
38
+ | Twilio, SendGrid, Mailgun, Resend | "a messaging provider" / "an email delivery service" |
39
+ | HubSpot, Salesforce, Pipedrive | "the Client's CRM" |
40
+ | Calendly, Cal.com, SavvyCal | "a scheduling tool" |
41
+ | Notion, Confluence, Coda | "a documentation system" |
42
+
43
+ If naming a third party is unavoidable for SOW clarity (e.g., "Operator will deliver a Shopify theme" when Shopify is the platform of the engagement), allow it — but treat it as the exception, not the default, and confirm with the user.
44
+
45
+ ## What to keep specific
46
+
47
+ - **The function the deliverable performs**: "normalizes, categorizes, and posts transactions"
48
+ - **The integration points by role**: "the Client's accounting system," "the Client's bank accounts," "the Client's chat tool"
49
+ - **Quantified scope**: "three bank accounts," "five user roles," "thirty days of tuning"
50
+ - **Outcome metrics or SLAs being committed to**
51
+ - **Process requirements**: idempotency, audit logging, review queues, breach-notification windows — these describe behavior, not tools
52
+ - **The Client's pre-existing tools** when the engagement specifically integrates with them — but phrase as "the Client's [function]" rather than naming the product. The product name can go in an Exhibit if needed.
53
+
54
+ ## Where specific tech *should* appear
55
+
56
+ - Internal tech specs (e.g., `docs/02-tech-spec.md`)
57
+ - Onboarding / kickoff docs that walk the Client through what will be set up
58
+ - Implementation runbooks
59
+ - Pitch decks and proposals — these are sales artifacts where naming tools can build credibility, but the resulting **contract** still abstracts them
60
+ - A separate "Technical Approach" Exhibit attached to the SOW (when the Client wants visibility) — phrased as "The Operator currently uses X to deliver this function; the Operator may substitute equivalent tooling without amendment, provided the function and outcome described in this Agreement are preserved."
61
+
62
+ ## Pre-send checklist
63
+
64
+ Before delivering any draft contract or SOW, search the document for these names and decide on each match:
65
+
66
+ ```
67
+ Plaid, Yodlee, Finicity, MX,
68
+ QuickBooks, QBO, Xero, NetSuite, Sage, FreshBooks,
69
+ n8n, Zapier, Make, Workato, Tray, Pipedream, Activepieces,
70
+ Anthropic, Claude, OpenAI, GPT, ChatGPT, Gemini, Llama, Mistral,
71
+ Slack, Teams, Discord, Google Chat,
72
+ Google Sheets, Airtable, Notion, Excel, Excel Online,
73
+ Google Drive, Dropbox, Box, OneDrive, SharePoint,
74
+ AWS, Amazon Web Services, GCP, Google Cloud, Azure,
75
+ DigitalOcean, Vercel, Heroku, Netlify, Cloudflare, Fly.io, Railway,
76
+ Postgres, PostgreSQL, MySQL, Mongo, MongoDB, Redis, DynamoDB, Supabase, Firebase,
77
+ GitHub, GitLab, Bitbucket,
78
+ Linear, Asana, Jira, Trello, ClickUp, Monday,
79
+ Stripe, Square, PayPal, Adyen, Braintree,
80
+ Twilio, SendGrid, Mailgun, Resend, Postmark,
81
+ HubSpot, Salesforce, Pipedrive, Close,
82
+ Calendly, Cal.com, SavvyCal,
83
+ Confluence, Coda
84
+ ```
85
+
86
+ For each match: keep it (only if the engagement is specifically about that product), or rewrite it functionally.
87
+
88
+ ## Rule of thumb
89
+
90
+ > If swapping the named tool for an equivalent would require zero change to the client's lived experience or the operator's commitments, the named tool doesn't belong in the contract.
91
+
92
+ ## Out of scope
93
+
94
+ - This skill is about **contracts and SOWs only**. Do NOT abstract product names in:
95
+ - Tech specs and engineering docs
96
+ - Onboarding instructions for the client's bookkeeper / admin / etc.
97
+ - Marketing/pitch artifacts
98
+ - Internal notes and runbooks
99
+ - Email replies that reference specific tools by name
@@ -0,0 +1,118 @@
1
+ ---
2
+ name: design-system
3
+ description: >-
4
+ The Install Agent Design System (v1.0) — canonical visual language for
5
+ every UI/on-screen surface: dark-mode, signal-red, tuned for
6
+ high-conversion sales funnels. Defines tokens (color, typography, spacing,
7
+ radii, container) and component specs (buttons, badges, cards, form inputs,
8
+ logo). Use this WHENEVER designing, building, or reviewing any UI, web
9
+ page, landing/funnel page, React/HTML component, marketing site section,
10
+ app screen, mockup, or prototype — even without saying "design system" or
11
+ "skill". Triggers: "build a landing page", "make a hero/CTA/pricing
12
+ section", "create a component", "style this", "make it on-brand", "match
13
+ our look", "what color/font/spacing", "dark theme", any front-end/UI task.
14
+ Source of truth is team-web/packages/ui (theme.css + components); this
15
+ skill mirrors it for use outside that repo. For PDFs/Excalidraw use
16
+ installagent-brand-kit instead; this one governs SCREENS.
17
+ ---
18
+
19
+ # Install Agent Design System v1.0
20
+
21
+ A system for high-conversion, dark-mode sales funnels. **Dark · Red · Hanken
22
+ Grotesk.** One signal-red accent does all the persuading; everything else is a
23
+ near-black neutral that gets out of the way.
24
+
25
+ Use this whenever you build or review a screen — a landing page, a funnel
26
+ section, a component, an app view, a mockup. It is the **screen** layer. Two
27
+ siblings complete the picture:
28
+
29
+ - **Code source of truth:** `team-web/packages/ui` — `theme.css` (tokens) +
30
+ `src/*` (components). When working in that repo, import from `@installagent/ui`
31
+ instead of re-implementing. **If a token ever disagrees, `theme.css` wins** —
32
+ update this skill in the same change.
33
+ - **Deliverables (print) brand layer:** `installagent-brand-kit` — client PDFs
34
+ and Excalidraw diagrams on white. Those live on light backgrounds and use the
35
+ *deep* red `#D11A1A`; this design system is dark-first and uses `#FF2D2D`.
36
+
37
+ Full token tables, component specs, and copy-paste values:
38
+ [`references/tokens.md`](references/tokens.md).
39
+
40
+ ## The system at a glance
41
+
42
+ **Color — one hue, dark surfaces.** Red is the *only* brand color. No blues or
43
+ greens for semantics — carry meaning with weight, glyphs (↑ ↓ → ✓), and the red
44
+ ramp (bright / deep / soft). Reserved status exceptions, never brand hues:
45
+ `star #F5A623` (review stars only), `success #30D158` + `success-soft`
46
+ (success/100% states on operational dashboards — the counterpart to
47
+ accent-as-error), and `warning #FFD60A` + `warning-soft` (silent/stale,
48
+ needs-attention-but-not-error dashboard states). Never on marketing surfaces.
49
+
50
+ | Group | Tokens |
51
+ |---|---|
52
+ | Surfaces (dark→light) | `canvas #070708` · `base #0E0E10` · `surface #141416` · `raised #1C1C20` · `overlay #26262B` |
53
+ | Accent · Signal Red | `accent #FF2D2D` (base) · `bright` (hover) · `deep #D11A1A` (pressed / on-white) · `soft` (22% tint) · foreground `#FFFFFF` |
54
+ | Status (reserved) | `star #F5A623` (review stars only) · `success #30D158` / `success-soft` (dashboard success states) · `warning #FFD60A` / `warning-soft` (dashboard stale/attention states) |
55
+ | Text | `primary #F5F5F6` · `secondary #C7C7CC` · `muted #9A9AA0` · `faint #6B6B70` |
56
+ | Borders | `hairline` (white @ 8%) · `line` · `line-strong` |
57
+
58
+ **Typography — Hanken Grotesk + JetBrains Mono.**
59
+
60
+ | Role | Face / weight | Size | Notes |
61
+ |---|---|---|---|
62
+ | Display | Hanken 800 | 56 | tracking −0.02em |
63
+ | Heading 1 / 2 / 3 | Hanken 800 / 700 / 700 | 40 / 28 / 20 | |
64
+ | Body Large / Body | Hanken 400 | 17 / 15 | line-height ~1.6 |
65
+ | Eyebrow / label | JetBrains Mono 600 | 12 | uppercase, +0.2em |
66
+
67
+ **Spacing scale (px):** `4 · 8 · 12 · 16 · 24 · 32 · 48 · 72 · 96`.
68
+ **Radius:** `sm 8 · md 14 · lg 24 · full 999` (pills). **Container:** max-width
69
+ `1160`, padding `40`.
70
+
71
+ ## Components (specs in references/tokens.md)
72
+
73
+ - **Buttons** — fully-rounded pills. `primary` (Signal Red, white label, soft
74
+ red glow, lifts 1px on hover), `secondary` (raised dark + hairline), `ghost`
75
+ (text only, reddens on hover). Sizes `sm · md · lg`, plus `disabled` (45%).
76
+ One red primary per view drives the conversion.
77
+ - **Badges & labels** — small pills: `accent` (soft-red fill), `neutral`,
78
+ `outline`. Section kickers use the mono eyebrow.
79
+ - **Cards & surfaces** — `surface`/`raised` panels, `md`/`lg` radius, hairline
80
+ border, subtle white-edge lift on hover.
81
+ - **Form inputs** — sit on `raised` dark fields with a hairline border and a red
82
+ focus ring. The funnel terminates in one embedded application form.
83
+ - **Logo** — the official Install Agent logo/mark only (see brand-kit assets).
84
+ Never a generic glyph.
85
+
86
+ ## How to apply it
87
+
88
+ **In `team-web`:** don't re-create any of this. Import from `@installagent/ui`
89
+ (`Button`, `Badge`, `Label`, `Card`, `Container`, `Section`, `Input`, `Field`,
90
+ `Logo`) and use the token utilities (`bg-accent`, `text-text-primary`,
91
+ `bg-raised`, `border-hairline`, `font-mono`…). Tokens live in `theme.css`; fonts
92
+ are loaded per-app via `next/font`. See `team-web/packages/ui/CLAUDE.md`.
93
+
94
+ **Anywhere else (a one-off HTML page, a prototype, a mockup, another repo):**
95
+ copy the values from `references/tokens.md`. Load **Hanken Grotesk** + **JetBrains
96
+ Mono** (Google Fonts). Build on a `#070708` canvas, use `#FF2D2D` for the single
97
+ primary CTA, keep body text `#C7C7CC` on dark.
98
+
99
+ ## Quality bar — before you ship a screen
100
+
101
+ - [ ] Dark canvas (`#070708`); surfaces step up `base → surface → raised → overlay`.
102
+ - [ ] Exactly **one** red primary CTA in view; secondary/ghost recede.
103
+ - [ ] One hue only — no off-brand blue/green; semantics ride weight + glyphs
104
+ (reserved exceptions: star gold on reviews, success green on dashboards).
105
+ - [ ] Hanken Grotesk for text, JetBrains Mono for eyebrows/labels.
106
+ - [ ] Pills are fully rounded; cards use `md`/`lg` radius; inputs have the red
107
+ focus ring.
108
+ - [ ] On white (rare for this system) use deep red `#D11A1A`, not `#FF2D2D`.
109
+ - [ ] Official logo, never a generic glyph; branding says Install Agent.
110
+ - [ ] In `team-web`: imported from `@installagent/ui`, no hardcoded hex.
111
+
112
+ ## Keeping it in sync
113
+
114
+ `team-web/packages/ui/theme.css` is the source of truth. If it changes, update
115
+ in the same pass: this skill's [`references/tokens.md`](references/tokens.md),
116
+ and — if the brand red/fonts moved — `installagent-brand-kit`
117
+ (`references/brand-tokens.md`, `scripts/brand.py`). Republish skills per
118
+ `skills/CLAUDE.md`.
@@ -0,0 +1,139 @@
1
+ # Install Agent Design System — tokens & component specs
2
+
3
+ The complete, copy-paste reference. The **source of truth** is
4
+ `team-web/packages/ui/theme.css`; these values mirror it. If they ever disagree,
5
+ `theme.css` wins — fix this file in the same change.
6
+
7
+ In `team-web`, never paste these hexes — use the token utilities
8
+ (`bg-accent`, `text-text-primary`, …). Paste them only for one-off pages or
9
+ prototypes outside the package.
10
+
11
+ ## 01 · Color
12
+
13
+ ### Canvas & surfaces (dark, near-black)
14
+
15
+ | Token | Hex | Use |
16
+ |---|---|---|
17
+ | `canvas` | `#070708` | Page background — the darkest layer. |
18
+ | `base` | `#0E0E10` | Base panels sitting on the canvas. |
19
+ | `surface` | `#141416` | Default card / surface. |
20
+ | `raised` | `#1C1C20` | Raised surface — inputs, hovered cards. |
21
+ | `overlay` | `#26262B` | Overlays, popovers, the topmost layer. |
22
+
23
+ ### Accent · Signal Red (the one brand hue)
24
+
25
+ | Token | Hex | Use |
26
+ |---|---|---|
27
+ | `accent` | `#FF2D2D` | Accent / Base — primary CTA, focus rings, the single red in a view. |
28
+ | `accent-bright` | `#FF5252` | Hover state of the primary. |
29
+ | `accent-deep` | `#D11A1A` | Pressed state — **and** the red to use on white/light backgrounds (legible where `#FF2D2D` is not). |
30
+ | `accent-soft` | `#FF2D2D` @ 22% | Soft tint fills, badge backgrounds, glows. |
31
+ | `accent-foreground` | `#FFFFFF` | Text/icons on top of the accent. |
32
+
33
+ **Rule:** red is the *only* brand color. No second hue for semantics. Use weight,
34
+ glyphs (↑ ↓ → ✓), and the red ramp to carry meaning.
35
+
36
+ ### Status (reserved, never brand hues)
37
+
38
+ | Token | Hex | Use |
39
+ |---|---|---|
40
+ | `star` | `#F5A623` | Review stars only. |
41
+ | `success` | `#30D158` | Success/100% states on operational dashboards (portal/admin) — the counterpart to accent-as-error. Never on marketing surfaces. |
42
+ | `success-soft` | `#30D158` @ 22% | Soft tints and glows behind success states. |
43
+ | `warning` | `#FFD60A` | Stale/silent agents, wiring gaps — dashboard states that need attention but aren't errors. Never on marketing surfaces. |
44
+ | `warning-soft` | `#FFD60A` @ 22% | Soft tints behind warning states. |
45
+
46
+ ### Text & borders
47
+
48
+ | Token | Hex / value | Use |
49
+ |---|---|---|
50
+ | `text-primary` | `#F5F5F6` | Headings, strong text. |
51
+ | `text-secondary` | `#C7C7CC` | Body copy. |
52
+ | `text-muted` | `#9A9AA0` | Secondary / supporting text. |
53
+ | `text-faint` | `#6B6B70` | Captions, labels, placeholders. |
54
+ | `hairline` | `rgba(255,255,255,0.08)` | Border / Hairline — the default divider on dark. |
55
+ | `line` | `#26262B` | Opaque divider. |
56
+ | `line-strong` | `#3A3A42` | Stronger divider / focus outline. |
57
+
58
+ ## 02 · Typography
59
+
60
+ Faces: **Hanken Grotesk** (display + body), **JetBrains Mono** (mono / eyebrow).
61
+ Both on Google Fonts. In the apps they're loaded via `next/font` and exposed as
62
+ `--font-hanken` / `--font-jetbrains-mono`, which the token stacks fall back to.
63
+
64
+ | Role | Face | Weight | Size (px) | Line-height | Tracking |
65
+ |---|---|---|---|---|---|
66
+ | Display | Hanken Grotesk | 800 | 56 | 1.05 | −0.02em |
67
+ | Heading 1 | Hanken Grotesk | 800 | 40 | 1.1 | −0.02em |
68
+ | Heading 2 | Hanken Grotesk | 700 | 28 | 1.15 | −0.01em |
69
+ | Heading 3 | Hanken Grotesk | 700 | 20 | 1.2 | −0.01em |
70
+ | Body Large | Hanken Grotesk | 400 | 17 | 1.6 | 0 |
71
+ | Body | Hanken Grotesk | 400 | 15 | 1.6 | 0 |
72
+ | Eyebrow / Label | JetBrains Mono | 600 | 12 | 1 | +0.2em, uppercase |
73
+
74
+ ## 03 · Spacing & layout
75
+
76
+ **Spacing scale (px):** `4 · 8 · 12 · 16 · 24 · 32 · 48 · 72 · 96`.
77
+
78
+ **Corner radius:** `sm 8` · `md 14` · `lg 24` · `full 999` (pills).
79
+
80
+ **Container:** max-width `1160px`, horizontal padding `40px`.
81
+
82
+ ## 04 · Buttons & controls
83
+
84
+ Fully-rounded pills (`full`). One red primary drives every conversion; secondary
85
+ and ghost recede into the dark.
86
+
87
+ | Variant | Fill | Label | Border | Hover |
88
+ |---|---|---|---|---|
89
+ | `primary` | `accent #FF2D2D` | white | — | `accent-bright`, lift 1px, soft red glow (`accent` @ 40%); pressed → `accent-deep` |
90
+ | `secondary` | `raised #1C1C20` | `text-primary` | `hairline` | `overlay`, `line-strong` border |
91
+ | `ghost` | transparent | `text-secondary` | — | label → `accent` |
92
+
93
+ **Sizes:** `sm` (px 16 / py 8, 12px) · `md` (px 20 / py 12, 14px) · `lg`
94
+ (px 28 / py 14, 16px). **Disabled:** 45% opacity, no pointer events.
95
+
96
+ ## 05 · Badges & labels
97
+
98
+ Small pills, `full` radius, 12px semibold.
99
+
100
+ | Tone | Fill | Text |
101
+ |---|---|---|
102
+ | `accent` | `accent-soft` | `accent` |
103
+ | `neutral` | `raised` | `text-secondary` |
104
+ | `outline` | transparent + `hairline` border | `text-muted` |
105
+
106
+ Section kickers / eyebrows: JetBrains Mono 600, 12px, uppercase, +0.2em, in
107
+ `text-faint`.
108
+
109
+ ## 06 · Cards & surfaces
110
+
111
+ `surface` or `raised` fill, `md`/`lg` radius, `hairline` border. On hover, a
112
+ subtle white-edge lift (border brightens ~18% toward white + a soft drop
113
+ shadow). Card title in `text-primary`, body in `text-secondary`, stat figures in
114
+ the display face.
115
+
116
+ ## 07 · Form inputs
117
+
118
+ Inputs sit on `raised` dark fields with a `hairline` border and a **red focus
119
+ ring** (`accent` border + `accent` @ 40% ring). Placeholder text is `text-faint`.
120
+ Radius `md`. Fields stack with a small `text-secondary` label above. The funnel
121
+ terminates in a single embedded application form.
122
+
123
+ ## 08 · Logo & brand
124
+
125
+ Use the **official Install Agent logo / mark** only (assets in
126
+ `installagent-brand-kit/assets/`): full lockup, or mark-only for tight spaces.
127
+ Never a generic glyph or re-creation. On a red fill, use the wordmark in white.
128
+
129
+ ## Mapping to `@installagent/ui` utilities
130
+
131
+ | Design token | Tailwind utility (in `team-web`) |
132
+ |---|---|
133
+ | `canvas` | `bg-canvas` (legacy `bg-bg`) |
134
+ | `surface` / `raised` / `overlay` | `bg-surface` / `bg-raised` (legacy `bg-surface-2`) / `bg-overlay` |
135
+ | `accent` / `accent-bright` / `accent-deep` / `accent-soft` | `bg-accent` `text-accent` / `bg-accent-bright` / `bg-accent-deep` / `bg-accent-soft` |
136
+ | `text-primary` / `secondary` / `muted` / `faint` | `text-text-primary` / `-secondary` / `-muted` / `-faint` (legacy `text-fg`, `text-muted`) |
137
+ | `hairline` / `line` / `line-strong` | `border-hairline` / `border-line` / `border-line-strong` |
138
+ | Hanken / JetBrains Mono | `font-sans` `font-display` / `font-mono` |
139
+ | radii | `rounded-sm` `rounded-md` `rounded-lg` `rounded-full` |