saasaloy 0.7.0 → 0.8.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.
- package/README.md +4 -2
- package/dist/index.js +222 -79
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/schemas/registry-item.schema.json +5 -2
- package/templates/base/AGENTS.md +80 -470
- package/templates/base/_agents/skills/saasaloy-design/SKILL.md +33 -22
- package/templates/base/_agents/skills/saasaloy-landing-copy/SKILL.md +17 -2
- package/templates/base/_agents/skills/saasaloy-setup/SKILL.md +38 -7
- package/templates/base/_saasaloy-base.json +1 -0
- package/templates/base/apps/web/DESIGN.md +4 -4
- package/templates/base/apps/web/astro.config.mjs +2 -1
- package/templates/base/apps/web/src/layouts/Layout.astro +2 -2
- package/templates/base/oxlint.config.mjs +14 -10
- package/templates/base/package.json +1 -0
- package/templates/base/packages/env/src/define.test.ts +33 -0
- package/templates/base/packages/ui/AGENTS.md +159 -0
- package/templates/base/packages/ui/CLAUDE.md +1 -0
- package/templates/base/packages/ui/components.json +1 -1
- package/templates/base/packages/ui/src/containers/README.md +4 -4
- package/templates/base/packages/ui/src/styles/brand.css +145 -0
- package/templates/base/packages/ui/src/styles/globals.css +6 -7
- package/templates/base/packages/ui/src/styles/web.css +7 -139
- package/templates/base/turbo.json +1 -0
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: saasaloy-design
|
|
3
|
-
description: Keep apps/web/DESIGN.md, and apps/admin/DESIGN.md when the admin app is installed, true of the Saasaloy design layer. Use theme to choose and apply a registry style to the web app, update after packages/ui changes, or audit a design contract for token drift.
|
|
3
|
+
description: Keep apps/web/DESIGN.md, and apps/admin/DESIGN.md when the admin app is installed, true of the Saasaloy design layer. Use theme to choose and apply a registry style to the web app, update after packages/ui changes, or audit a design contract for token drift. Under autonomy: afk in docs/product-brief.md, theme picks the preset from the brief without asking.
|
|
4
4
|
derived-from: "designkit (MIT), narrowed 2026-08-09"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# saasaloy-design
|
|
8
8
|
|
|
9
|
-
This skill records the design system that the project already uses. It writes no components and no pages.
|
|
9
|
+
This skill records the design system that the project already uses. It writes no components and no pages. For that work, follow `packages/ui/AGENTS.md`.
|
|
10
10
|
|
|
11
11
|
Each app has its own token home and its own contract:
|
|
12
12
|
|
|
13
13
|
| App | Token home | Contract |
|
|
14
14
|
|-----|------------|----------|
|
|
15
|
-
| web | `packages/ui/src/styles/
|
|
15
|
+
| web | `packages/ui/src/styles/brand.css` | `apps/web/DESIGN.md` |
|
|
16
16
|
| admin, when installed | `packages/ui/src/styles/admin.css` | `apps/admin/DESIGN.md` |
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
`brand.css` and `admin.css` both import `packages/ui/src/styles/globals.css`, which holds the shared Tailwind setup and no token values. The web app's stylesheet, `packages/ui/src/styles/web.css`, imports `brand.css` and adds the landing page's layout, type and motion vocabulary. Ask which app when the user does not say, and work on one contract at a time. Never read one app's tokens into the other app's contract.
|
|
19
19
|
|
|
20
|
-
The admin contract also covers the
|
|
20
|
+
The admin contract also covers the shell primitive set in `packages/ui/src/components/shell/`, its blocks in `packages/ui/src/blocks/shell/`, its containers in `packages/ui/src/containers/shell/` and the defaults in `packages/ui/src/styles/shell.css`, as `admin.css` overrides them. The web contract covers the base `components/`, the other `blocks/` and the web app.
|
|
21
21
|
|
|
22
22
|
The grounding rule controls every mode. Every token value must exist in the project code or in the Tailwind utility that the project uses. Do not choose a nearby value because it looks cleaner.
|
|
23
23
|
|
|
@@ -27,17 +27,17 @@ The grounding rule controls every mode. Every token value must exist in the proj
|
|
|
27
27
|
- `update` re-derives the contract after a design layer change, writes a new fingerprint, and lints the result.
|
|
28
28
|
- `audit` checks the fingerprint and the contract. It never writes.
|
|
29
29
|
|
|
30
|
-
If the user does not name a mode, ask which mode to use. Do not choose between a write and an audit.
|
|
30
|
+
If the user does not name a mode, ask which mode to use. Do not choose between a write and an audit. The one exception is an unattended run: see [Unattended run](#unattended-run).
|
|
31
31
|
|
|
32
32
|
## Write surface
|
|
33
33
|
|
|
34
34
|
| Mode | Files |
|
|
35
35
|
|------|-------|
|
|
36
|
-
| `theme` | web only: `packages/ui/src/styles/
|
|
37
|
-
| `update` | the chosen app's `DESIGN.md`
|
|
38
|
-
| `audit` | none |
|
|
36
|
+
| `theme` | web only: `packages/ui/src/styles/brand.css`, `apps/web/DESIGN.md`, `docs/product-brief.md` only when the brief is absent, and `docs/build-log.md` under `autonomy: afk` |
|
|
37
|
+
| `update` | the chosen app's `DESIGN.md`, and `docs/build-log.md` under `autonomy: afk` |
|
|
38
|
+
| `audit` | none, under `autonomy: afk` too |
|
|
39
39
|
|
|
40
|
-
`theme` never runs for the admin app. A preset targets `
|
|
40
|
+
`theme` never runs for the admin app. A preset targets `brand.css` through `components.json`, and nothing writes to `admin.css` but a person. When the user asks to restyle the admin app, say so, and offer `update` after they edit `admin.css`.
|
|
41
41
|
|
|
42
42
|
Do not edit `components.json` during a theme change. Do not add a dependency, script, component, page, or Tailwind class.
|
|
43
43
|
|
|
@@ -61,7 +61,7 @@ Write elevation as prose under `## Elevation & Depth`. Never add `elevation` to
|
|
|
61
61
|
|
|
62
62
|
Write motion as prose under `## Motion`. The alpha schema has no motion token group and no component transition token.
|
|
63
63
|
|
|
64
|
-
The landing page's layout, type and motion vocabulary lives
|
|
64
|
+
The landing page's layout, type and motion vocabulary lives in `web.css`, after its import of `brand.css`, and `DESIGN.md` must name all of it:
|
|
65
65
|
|
|
66
66
|
- The type ramp in `@theme`: `--text-display`, `--text-section-title` and `--text-lead`. Record the largest size of each fluid `clamp()` step as the token's `fontSize`, and describe the fluid range in the Typography prose.
|
|
67
67
|
- The container widths in `@theme` (`--container-page`, `--container-narrow`, `--container-wide`) and the `section-container*` and `section-y` utilities. Describe them under `## Layout`. Spacing stays omitted, because these are named widths and one section rhythm, not a spacing scale.
|
|
@@ -78,24 +78,24 @@ The web contract is a one-time base seed. ADR 0022 means Saasaloy has no update
|
|
|
78
78
|
|
|
79
79
|
## Fingerprint
|
|
80
80
|
|
|
81
|
-
The fingerprint covers only the chosen app's
|
|
81
|
+
The fingerprint covers only the chosen app's token home: `packages/ui/src/styles/brand.css` for the web contract, `packages/ui/src/styles/admin.css` for the admin contract. It does not cover `globals.css`, `web.css`, components, blocks, or other files. The commands and stamps below name `brand.css`; substitute `admin.css` for the admin contract.
|
|
82
82
|
|
|
83
83
|
Compute the fingerprint from the file bytes. Use the first 12 lowercase hexadecimal characters of SHA-256.
|
|
84
84
|
|
|
85
85
|
```sh
|
|
86
|
-
node --input-type=module -e "import { createHash } from 'node:crypto'; import { readFileSync } from 'node:fs'; process.stdout.write(createHash('sha256').update(readFileSync('packages/ui/src/styles/
|
|
86
|
+
node --input-type=module -e "import { createHash } from 'node:crypto'; import { readFileSync } from 'node:fs'; process.stdout.write(createHash('sha256').update(readFileSync('packages/ui/src/styles/brand.css')).digest('hex').slice(0, 12))"
|
|
87
87
|
```
|
|
88
88
|
|
|
89
89
|
The scaffold seed ends with this stamp.
|
|
90
90
|
|
|
91
91
|
```markdown
|
|
92
|
-
_Seeded from the saasaloy base template · CLI <version> · tokens sha256:<12 hex> of packages/ui/src/styles/
|
|
92
|
+
_Seeded from the saasaloy base template · CLI <version> · tokens sha256:<12 hex> of packages/ui/src/styles/brand.css_
|
|
93
93
|
```
|
|
94
94
|
|
|
95
95
|
After `theme` or `update`, replace the seed stamp with this stamp.
|
|
96
96
|
|
|
97
97
|
```markdown
|
|
98
|
-
_Updated from packages/ui on YYYY-MM-DD · tokens sha256:<12 hex> of packages/ui/src/styles/
|
|
98
|
+
_Updated from packages/ui on YYYY-MM-DD · tokens sha256:<12 hex> of packages/ui/src/styles/brand.css_
|
|
99
99
|
```
|
|
100
100
|
|
|
101
101
|
Do not change the fingerprint during `audit`.
|
|
@@ -123,7 +123,7 @@ If the network or `pnpm dlx` is unavailable, continue with the fingerprint and l
|
|
|
123
123
|
|
|
124
124
|
### 1. Read the product context
|
|
125
125
|
|
|
126
|
-
Read `docs/product-brief.md` first. Use its product, audience, differentiator, tone, and language answers. Do not ask those questions again.
|
|
126
|
+
Read `docs/product-brief.md` first. When its frontmatter holds `autonomy: afk`, follow [Unattended run](#unattended-run). Use its product, audience, differentiator, tone, and language answers. Do not ask those questions again.
|
|
127
127
|
|
|
128
128
|
If the brief is absent, offer to run `saasaloy-setup`:
|
|
129
129
|
|
|
@@ -147,13 +147,13 @@ Use the package-local executable from the project root.
|
|
|
147
147
|
pnpm --filter @repo/ui exec shadcn add <registry-style-url>
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
`components.json` points shadcn at `
|
|
150
|
+
`components.json` points shadcn at `brand.css`, so the preset merges into the `:root`, `.dark` and `@theme inline` blocks there. Confirm that `globals.css` and `web.css` did not change, that `globals.css` still holds the `@source` rules and `@layer base`, and that `web.css` still holds the landing vocabulary. Confirm that `globals.css`, `brand.css` and `web.css` hold one `@theme inline` and one `@custom-variant dark` between them. Confirm that `components.json` did not change.
|
|
151
151
|
|
|
152
152
|
Stop and report the failure when the preset removes a required rule or changes `components.json`. Do not repair an unknown preset merge without approval.
|
|
153
153
|
|
|
154
154
|
### 4. Re-derive the contract
|
|
155
155
|
|
|
156
|
-
Run the shared extraction process against the merged `web.css
|
|
156
|
+
Run the shared extraction process against the merged `brand.css`, the landing vocabulary in `web.css`, and their usage. Update the token front matter and only the prose sections that the new tokens affect.
|
|
157
157
|
|
|
158
158
|
Use the product brief to update Overview and Do's and Don'ts. Do not add product claims that the brief does not support.
|
|
159
159
|
|
|
@@ -161,7 +161,18 @@ Recompute and replace the fingerprint stamp. Run the official linter.
|
|
|
161
161
|
|
|
162
162
|
### 5. Report
|
|
163
163
|
|
|
164
|
-
Name the registry style URL. List the changed token groups and the new fingerprint. State the linter result. Tell the user
|
|
164
|
+
Name the registry style URL. List the changed token groups and the new fingerprint. State the linter result. Tell the user that component or page work follows `packages/ui/AGENTS.md`.
|
|
165
|
+
|
|
166
|
+
## Unattended run
|
|
167
|
+
|
|
168
|
+
`autonomy: afk` in the frontmatter of `docs/product-brief.md` means nobody is at the keyboard. Ask nothing, and wait for no approval. When a person in this conversation asks to choose the theme or to approve it, take the attended path instead.
|
|
169
|
+
|
|
170
|
+
1. **Pick the mode.** With no mode named, run `theme` for the web app. A named mode runs as named. `theme` never runs for the admin app, here as anywhere.
|
|
171
|
+
2. **Read the brief instead of asking.** Take the colour mood and the density from the Tone answer, the Audience answer and the site the owner pointed at. Ask no design question.
|
|
172
|
+
3. **Pick one registry style that fits the tone.** Take a tweakcn theme, served at `https://tweakcn.com/r/themes/<name>.json`, as [step 2 of `theme`](#2-choose-the-registry-style) allows. `https://ui.shadcn.com/create` needs a person at a browser, so it is not an option here. Fetch the URL first and check that it serves a `registry:style` item. Do not invent a palette, and do not write token values by hand.
|
|
173
|
+
4. **Apply it and re-derive the contract** with steps 3 and 4 of `theme`, with no preview and no approval. First copy `brand.css` and `components.json` to a temporary folder outside the repo, because a fresh project may have no commit to restore them from. Every check in step 3 still applies. When the preset removes a required rule or changes `components.json`, copy both files back and log the failure under `## Blocked`.
|
|
174
|
+
5. **Fall back when you cannot reach a registry.** With no network, keep the shipped theme, run `update` on `apps/web/DESIGN.md` only if its fingerprint is stale, adding or deleting no section, and list the theme choice under `## Left for a human`.
|
|
175
|
+
6. **Log the run** in `docs/build-log.md`: the registry style URL, one line on why it fits the brief's tone, and the linter result. Add the lines under the current stage's `##` section when a build is running, and under a new `## Design` section when none is. Create the log with a `# Build log` title when it does not exist. Leave the fingerprint out: the log's reader takes the first hex string in a section as its commit. The stage that commits adds its commit hash to that section.
|
|
165
176
|
|
|
166
177
|
## `update`
|
|
167
178
|
|
|
@@ -189,7 +200,7 @@ Audit is read-only. Do not edit or format any file.
|
|
|
189
200
|
|
|
190
201
|
### 1. Check the fingerprint offline
|
|
191
202
|
|
|
192
|
-
Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from the chosen app's
|
|
203
|
+
Read the recorded 12-character fingerprint from the final stamp. Compute the current fingerprint from the chosen app's token home, `brand.css` or `admin.css`.
|
|
193
204
|
|
|
194
205
|
- `current` means the two fingerprints match.
|
|
195
206
|
- `stale` means they differ.
|
|
@@ -211,9 +222,9 @@ Open with the file count that the audit scanned. Give one verdict for the finger
|
|
|
211
222
|
|
|
212
223
|
## Boundaries
|
|
213
224
|
|
|
214
|
-
- Never write a component or a page.
|
|
225
|
+
- Never write a component or a page. That work follows `packages/ui/AGENTS.md`.
|
|
215
226
|
- Never add a token value that the project does not contain.
|
|
216
|
-
- Never change `globals.css` in any mode, or `
|
|
227
|
+
- Never change `globals.css` or `web.css` in any mode, or `brand.css` in `update` or `audit`.
|
|
217
228
|
- Never write during `audit`.
|
|
218
229
|
- Never claim that lint passed when the linter did not run.
|
|
219
230
|
- Never treat a matching fingerprint as proof that component usage has no drift.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: saasaloy-landing-copy
|
|
3
|
-
description: Write the scaffolded landing page's copy from docs/product-brief.md — as a markdown draft the owner reviews first, then into the content module. Use when the landing page still describes Saasaloy ("Ship the SaaS, not the scaffolding"), when the owner asks to write, rewrite, improve or update the landing copy, headline, features, pricing or FAQ,
|
|
3
|
+
description: Write the scaffolded landing page's copy from docs/product-brief.md — as a markdown draft the owner reviews first, then into the content module. Use when the landing page still describes Saasaloy ("Ship the SaaS, not the scaffolding"), when the owner asks to write, rewrite, improve or update the landing copy, headline, features, pricing or FAQ, when re-running after the brief changed, and when an unattended build runs on a brief with autonomy: afk. Needs docs/product-brief.md; run saasaloy-setup first if there isn't one.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# saasaloy-landing-copy — draft it in markdown, then write the page
|
|
@@ -23,6 +23,7 @@ reviewed.
|
|
|
23
23
|
| `packages/ui/src/content/landing.ts` | Everything under `landing.*`. Plus `ui.*`, **translated only**, and only when the page is not in English — see [Language](#language-and-the-ui-namespace). |
|
|
24
24
|
| `apps/web/src/pages/index.astro` | Only to drop a block, and only behind its own confirmation. |
|
|
25
25
|
| `docs/product-brief.md` | Only to append what you learned filling a gap the brief left, and only its **Known gaps** section otherwise. |
|
|
26
|
+
| `docs/build-log.md` | Under `autonomy: afk` only: the run's lines in the current stage's section, or in a `## Landing copy` section, and the items it adds to `## Left for a human` or `## Blocked`. |
|
|
26
27
|
|
|
27
28
|
Nothing else — in particular not `packages/config/src/project.ts`, which holds the product
|
|
28
29
|
name and the locale. Those are project identity, `saasaloy-setup` owns them, and
|
|
@@ -31,7 +32,7 @@ brief.
|
|
|
31
32
|
|
|
32
33
|
## Step 0 — before you write anything
|
|
33
34
|
|
|
34
|
-
1. **Read `docs/product-brief.md`.** No brief, no copy. Say so and offer to run
|
|
35
|
+
1. **Read `docs/product-brief.md`.** If its frontmatter holds `autonomy: afk`, follow [Unattended run](#unattended-run) instead of the steps below, unless a person in this conversation asks for the draft and the review. Then take the attended path. No brief, no copy. Say so and offer to run
|
|
35
36
|
`saasaloy-setup`:
|
|
36
37
|
|
|
37
38
|
> There's no `docs/product-brief.md`, so I'd be writing about a product I know nothing
|
|
@@ -362,6 +363,19 @@ It is three edits, and all three are allowed:
|
|
|
362
363
|
Removing a block is not redesigning one. You are editing lines in a page, not editing
|
|
363
364
|
`packages/ui/src/blocks/`.
|
|
364
365
|
|
|
366
|
+
## Unattended run
|
|
367
|
+
|
|
368
|
+
`autonomy: afk` in the brief's frontmatter means nobody is at the keyboard. Write the page from the brief with no draft approval and no question, and record every decision in `docs/build-log.md`, which is where the owner reviews it later. Every rule in Steps 1 to 5 still holds, except where this section replaces it.
|
|
369
|
+
|
|
370
|
+
1. **Read the brief, the content module and the icon registry**, as [Step 0](#step-0--before-you-write-anything) says.
|
|
371
|
+
2. **Ask nothing.** Write around every gap and every `weak:` tag the brief left, the way [Step 1](#step-1--fill-only-the-gaps-the-brief-left) says to when a gap stays a gap: describe what the product does, and leave the claim out.
|
|
372
|
+
3. **Write no draft file, and wait for no review.** Skip Steps 2 and 3. When a `docs/landing-copy-draft.md` from an earlier run is on disk, leave it alone and list it under `## Left for a human`.
|
|
373
|
+
4. **Leave hand-written copy alone.** When the content module has been rewritten by hand and the brief does not explain it, write nothing to it. List it under `## Left for a human` and stop.
|
|
374
|
+
5. **Write `landing.ts`** as [Step 4](#step-4--write-the-content-module) says, with no confirmation. First copy `landing.ts` and `apps/web/src/pages/index.astro` to a temporary folder outside the repo, because a fresh project may have no commit to restore them from.
|
|
375
|
+
6. **Drop a block only when the brief gives it nothing true to carry**: no pricing yet, no named customer for the quotes or the logos, no real sequence for how it works. Make the three edits in [Dropping a block](#dropping-a-block-is-its-own-confirmation), retarget each action that pointed at it, and log the drop. Pricing marked as placeholder keeps the shipped tiers, and that goes under `## Left for a human`.
|
|
376
|
+
7. **Prove it** with [Step 5](#step-5--prove-it-then-clean-up)'s two commands. When you cannot fix a red build, copy both files back from the temporary folder and log the failure under `## Blocked`.
|
|
377
|
+
8. **Log the run** in `docs/build-log.md`: the sections you rewrote, each block you dropped and why, and the lines you are least sure about. Add the lines under the current stage's `##` section when a build is running, and under a new `## Landing copy` section when none is. The stage that commits adds its commit hash to that section. Add each **Not mine to fix** item, such as a name or locale that disagrees with the brief, under `## Left for a human`. Create the log with a `# Build log` title when it does not exist.
|
|
378
|
+
|
|
365
379
|
## Re-running
|
|
366
380
|
|
|
367
381
|
Copy on disk plus a brief means this has run before.
|
|
@@ -408,6 +422,7 @@ Copy on disk plus a brief means this has run before.
|
|
|
408
422
|
under the next bullet, and for a page-specific gap ask only the questions
|
|
409
423
|
[Step 1](#step-1--fill-only-the-gaps-the-brief-left) allows. Never ask the setup
|
|
410
424
|
interview's own questions yourself.
|
|
425
|
+
- **Under `autonomy: afk`, never ask and never wait.** Log the decision in `docs/build-log.md` instead.
|
|
411
426
|
- **A dirty tree, a missing repo, or a thin brief is not a blocker.** Warn, write less, and
|
|
412
427
|
say what you left out. (This is about those three conditions only — anything unsafe or
|
|
413
428
|
outside this skill's scope you decline as you normally would.)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: saasaloy-setup
|
|
3
|
-
description: Interview the project owner about their product once, and write the answers to docs/product-brief.md — the shared context every other Saasaloy skill reads. Use at the start of a freshly scaffolded project, when the owner says "set up this project", "tell you about my product", "what is this project", when config.app.name is still the shipped "Saasaloy", when another skill needs product context and no brief exists yet,
|
|
3
|
+
description: Interview the project owner about their product once, and write the answers to docs/product-brief.md — the shared context every other Saasaloy skill reads. Use at the start of a freshly scaffolded project, when the owner says "set up this project", "tell you about my product", "what is this project", when config.app.name is still the shipped "Saasaloy", when another skill needs product context and no brief exists yet, when re-running to update the brief after something changed, and when an unattended build starts on a brief whose frontmatter says autonomy: afk.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# saasaloy-setup — find out what this project is, once
|
|
@@ -21,14 +21,14 @@ It writes no copy. `saasaloy-landing-copy` does that, from the brief this leaves
|
|
|
21
21
|
|------|-----------------|
|
|
22
22
|
| `docs/product-brief.md` | The whole file. Create `docs/` if it does not exist. |
|
|
23
23
|
| `packages/config/src/project.ts` | `app.name` and `app.locale`, and nothing else in the file. |
|
|
24
|
+
| `docs/build-log.md` | Under `autonomy: afk` only: the run's lines in the current stage's section, or in a `## Setup` section, or the `## Blocked` list. |
|
|
24
25
|
|
|
25
26
|
Nothing else. You are not here to write the landing page, add a dependency, or touch a
|
|
26
27
|
block.
|
|
27
28
|
|
|
28
29
|
## Step 0 — before you ask anything
|
|
29
30
|
|
|
30
|
-
1. **Read `docs/product-brief.md`.** If it exists, someone has already been through this.
|
|
31
|
-
Read it fully and jump to [Re-running](#re-running).
|
|
31
|
+
1. **Read `docs/product-brief.md`.** If its frontmatter holds `autonomy: afk`, follow [Unattended run](#unattended-run) and ask nothing, unless a person in this conversation asks for the interview, a change to the brief, or to turn unattended runs off. Then take the attended path below. Otherwise, if it exists, someone has already been through this. Read it fully and jump to [Re-running](#re-running).
|
|
32
32
|
2. **Read `packages/config/src/project.ts`** for the current `app.name`. It ships
|
|
33
33
|
commented out, so the name is still the base's `"Saasaloy"` until someone sets it. When
|
|
34
34
|
it is set, it is the best opening guess you have, and it belongs in question 1's
|
|
@@ -36,8 +36,9 @@ block.
|
|
|
36
36
|
3. **Look at git, and treat it as advice.** `git status --short` if there is a repo. A dirty
|
|
37
37
|
tree or no repo at all is worth one sentence — "your changes aren't committed, so you
|
|
38
38
|
can't undo this with git; every write here is previewed and confirmed anyway" — and then
|
|
39
|
-
you carry on. `saasaloy init`
|
|
40
|
-
|
|
39
|
+
you carry on. `saasaloy init` creates the repository unless it ran with `--no-git`, and
|
|
40
|
+
a fresh scaffold has no commit yet, so a clean-tree requirement would block exactly the
|
|
41
|
+
person who just scaffolded. **Neither state is a reason to stop.**
|
|
41
42
|
4. **Say how long this takes and what it is for**, in two lines, before question 1. Ten
|
|
42
43
|
questions is a real ask, and an owner who does not know why is an owner who answers
|
|
43
44
|
thinly.
|
|
@@ -65,6 +66,14 @@ number.
|
|
|
65
66
|
| 9 | **Pricing** | Per tier: name, who it is for, real monthly price, annual price if there is one. See [Pricing](#pricing-is-extracted-never-invented). |
|
|
66
67
|
| 10 | **Where "sign up" goes** | The signup, waitlist or app URL the primary button should point at. See [The destination](#the-destination-question). |
|
|
67
68
|
|
|
69
|
+
Then ask one more question, last and on its own: **"Run the build unattended?"** It is not an eleventh brief section. It decides whether an agent may later build the project with nobody at the keyboard, so a person must answer it. Offer two samples and no third:
|
|
70
|
+
|
|
71
|
+
> **Run the build unattended?**
|
|
72
|
+
> a. No — I'll stay at the keyboard and answer each skill's questions.
|
|
73
|
+
> b. Yes — write `autonomy: afk` into the brief, so the build skills run without asking me.
|
|
74
|
+
|
|
75
|
+
On yes, write `autonomy: afk` into the brief's frontmatter. Before you write it, check the brief is [complete](#unattended-run): when an answer is missing or tagged `weak:`, name each one and say that an unattended run stops at those sections until they are filled. On no, write no `autonomy` field, and remove one an earlier run wrote.
|
|
76
|
+
|
|
68
77
|
### Every question ships with sample answers
|
|
69
78
|
|
|
70
79
|
Never ask a bare question. Each one carries **three sample answers the owner can take as
|
|
@@ -115,6 +124,8 @@ An answer is **weak** when it names no audience, no number, no named alternative
|
|
|
115
124
|
proof the owner could point at. "Everyone" is not an audience. "It's faster" is not a
|
|
116
125
|
differentiator. "Businesses struggle with productivity" is not a problem.
|
|
117
126
|
|
|
127
|
+
An honest empty answer is not weak. "No proof yet", "no pricing yet" and "nothing to link to yet" are facts the owner stated, so record them as plain text with no `weak:` tag.
|
|
128
|
+
|
|
118
129
|
Push back **at most twice per question**, and make each follow-up narrower than the last —
|
|
119
130
|
carrying fresh samples, same as the first ask:
|
|
120
131
|
|
|
@@ -164,8 +175,8 @@ Ask where the primary call to action should go. Three answers to expect:
|
|
|
164
175
|
- **A URL.** Record it. An external form, a waitlist provider, an app subdomain.
|
|
165
176
|
- **A route this project will have later** (`/signup`). Record it, and note it does not
|
|
166
177
|
exist yet.
|
|
167
|
-
- **Nothing yet.** Record
|
|
168
|
-
|
|
178
|
+
- **Nothing yet.** Record "nothing to link to yet", with no `weak:` tag. The page keeps
|
|
179
|
+
sending people to its own closing section, and the labels have to stay modest to match.
|
|
169
180
|
|
|
170
181
|
## Step 2 — write the brief
|
|
171
182
|
|
|
@@ -210,6 +221,14 @@ https://ledgerly.com.bd/waitlist — a Tally form, live now.
|
|
|
210
221
|
visitor's device provides.
|
|
211
222
|
```
|
|
212
223
|
|
|
224
|
+
On a yes to "Run the build unattended?", put this frontmatter above the `# Product brief` title. On a no, leave it out:
|
|
225
|
+
|
|
226
|
+
```md
|
|
227
|
+
---
|
|
228
|
+
autonomy: afk
|
|
229
|
+
---
|
|
230
|
+
```
|
|
231
|
+
|
|
213
232
|
Two rules about this file:
|
|
214
233
|
|
|
215
234
|
- **Keep every `weak:` tag verbatim.** It is the thread the next run picks up.
|
|
@@ -254,6 +273,17 @@ A brief on disk means the interview already happened.
|
|
|
254
273
|
4. **If the brief was hand-edited**, that wins. Do not tidy someone's prose back into your
|
|
255
274
|
own phrasing.
|
|
256
275
|
|
|
276
|
+
## Unattended run
|
|
277
|
+
|
|
278
|
+
`autonomy: afk` in the brief's frontmatter means a person answered yes to "Run the build unattended?" and is not at the keyboard now. Ask nothing in this run: no question, no confirmation, no preview that waits for an answer. The attended interview above never runs here, because only a person can write the brief.
|
|
279
|
+
|
|
280
|
+
1. **Check that the brief is complete.** It is complete when all ten answers are present and filled: Name, Language, Audience, Problem, Current alternative, Differentiator, Proof, Tone, Pricing, and Where "sign up" goes. An honest empty answer ("no proof yet", "no pricing yet") counts as filled. An answer tagged `weak:`, a missing section, or an empty one does not. `Known gaps` and any extra section are not checked.
|
|
281
|
+
2. **With an incomplete brief, stop.** Append each missing, empty or weak section to `docs/build-log.md` under `## Blocked`, one list item each, naming the section and what is wrong (`- Product brief: Proof is empty`). Create the file with a `# Build log` title when it does not exist, and add the `## Blocked` heading when it is not there. End the list with `- Product brief: fill these sections with /saasaloy-setup, or delete the autonomy line to work attended`. Write nothing else, and stop the run. An unattended build does not start the first module with a brief that is not complete.
|
|
282
|
+
3. **With a complete brief, set the two facts that are code.** Set `app.name` from Name and `app.locale` from Language's code in `packages/config/src/project.ts`, exactly as [Step 3](#step-3--set-the-two-facts-that-are-code) says, with no confirmation. Leave either one alone when it already matches the brief. Run `pnpm typecheck`.
|
|
283
|
+
4. **Log what you did** in `docs/build-log.md`: the name and the locale you set, or that both already matched, and the `pnpm typecheck` result. Add the lines under the current stage's `##` section when a build is running, and under a new `## Setup` section when none is. Write no hex string other than a commit hash, because the log's reader takes the first one in a section as its commit. The stage that commits adds its commit hash to that section.
|
|
284
|
+
|
|
285
|
+
Never edit the brief in this run. A wrong answer in it is the owner's to fix.
|
|
286
|
+
|
|
257
287
|
## What happens next
|
|
258
288
|
|
|
259
289
|
Say so explicitly when you finish, because the brief on its own changes nothing the owner
|
|
@@ -276,6 +306,7 @@ can see:
|
|
|
276
306
|
a sample answer.
|
|
277
307
|
- **No dependencies, no i18n machinery, no webfonts.** Record the gap in the brief; do not
|
|
278
308
|
close it.
|
|
309
|
+
- **Under `autonomy: afk`, never ask.** Write the `## Blocked` list and stop instead.
|
|
279
310
|
- **A dirty tree, a missing repo, or a thin interview is not a blocker.** Warn, record less,
|
|
280
311
|
and say what you left out. (This is about those three conditions only — anything unsafe
|
|
281
312
|
or outside this skill's scope you decline as you normally would.)
|
|
@@ -176,13 +176,13 @@ The base uses a neutral, content-first system. It gives a new product a clear st
|
|
|
176
176
|
|
|
177
177
|
## Apps
|
|
178
178
|
|
|
179
|
-
This file covers the web app. Each app has its own
|
|
179
|
+
This file covers the web app. Each app has its own stylesheet in `packages/ui/src/styles/` and its own `DESIGN.md` in its own folder. `brand.css` holds the tokens recorded here, `web.css` imports it and adds the landing page's layout, type and motion vocabulary, and `globals.css` holds the shared Tailwind setup with no token values. Another app's theme file, such as `admin.css`, imports `globals.css` and declares its own tokens, mapping and radius scale, so a change here never reaches it.
|
|
180
180
|
|
|
181
181
|
## Colors
|
|
182
182
|
|
|
183
183
|
The light theme uses white surfaces, near-black text, and a dark neutral primary action. The dark theme reverses that relationship with near-black surfaces and near-white text. Muted neutrals separate supporting content. The destructive color is the only chromatic semantic token in the seed.
|
|
184
184
|
|
|
185
|
-
Use the semantic custom properties in `packages/ui/src/styles/
|
|
185
|
+
Use the semantic custom properties in `packages/ui/src/styles/brand.css`. Do not copy their current `oklch()` values into components.
|
|
186
186
|
|
|
187
187
|
## Typography
|
|
188
188
|
|
|
@@ -214,7 +214,7 @@ The `error-state` block is the one screen for a failure: a wrong path, a failed
|
|
|
214
214
|
|
|
215
215
|
## Do's and Don'ts
|
|
216
216
|
|
|
217
|
-
- Read this file and `packages/ui/src/styles/web.css` before you write UI.
|
|
217
|
+
- Read this file, `packages/ui/src/styles/brand.css` and `packages/ui/src/styles/web.css` before you write UI.
|
|
218
218
|
- Use semantic token utilities such as `bg-primary` and `text-muted-foreground`.
|
|
219
219
|
- Keep light and dark token pairs together when you change a semantic role.
|
|
220
220
|
- Keep new pages within the established type scale and radius vocabulary.
|
|
@@ -234,4 +234,4 @@ The `.dark` class selects the dark token set. The pre-paint theme script applies
|
|
|
234
234
|
|
|
235
235
|
The theme toggle has two states, light and dark. `system` is only the starting state: a visitor who never pressed the toggle follows the OS. A press flips the resolved mode and stores the choice, and no press steps back to `system`. Do not add a third state or a light/dark/system menu to the toggle.
|
|
236
236
|
|
|
237
|
-
_Seeded from the saasaloy base template · CLI {{CLI_VERSION}} · tokens sha256:
|
|
237
|
+
_Seeded from the saasaloy base template · CLI {{CLI_VERSION}} · tokens sha256:d7c3ad027b63 of packages/ui/src/styles/brand.css_
|
|
@@ -79,7 +79,8 @@ export default defineConfig({
|
|
|
79
79
|
vite: {
|
|
80
80
|
// Tailwind 4 is a Vite plugin, not an Astro integration — `@astrojs/tailwind` is EOL
|
|
81
81
|
// and never supported v4. The theme lives in packages/ui: the @source globs in
|
|
82
|
-
// src/styles/globals.css, the tokens in src/styles/
|
|
82
|
+
// src/styles/globals.css, the tokens in src/styles/brand.css, and the landing
|
|
83
|
+
// utilities in src/styles/web.css, which imports brand.css and which Layout.astro
|
|
83
84
|
// imports via `@repo/ui/styles/web.css`.
|
|
84
85
|
plugins: [tailwindcss()],
|
|
85
86
|
server: { strictPort: true },
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
// The one document shell for every page. It owns <html>/<head>/<body> and the single
|
|
3
3
|
// import of the web theme, so a page is only ever its own content — no page may
|
|
4
|
-
// duplicate the shell or import a stylesheet again. web.css imports the
|
|
5
|
-
//
|
|
4
|
+
// duplicate the shell or import a stylesheet again. web.css imports brand.css, the
|
|
5
|
+
// tokens, and brand.css imports the shared globals.css.
|
|
6
6
|
import { config } from "@repo/config";
|
|
7
7
|
import "@repo/ui/styles/web.css";
|
|
8
8
|
import { siteName } from "@repo/ui";
|
|
@@ -174,18 +174,22 @@ export default defineConfig({
|
|
|
174
174
|
rules: { "unicorn/filename-case": "off" },
|
|
175
175
|
},
|
|
176
176
|
|
|
177
|
-
// The
|
|
178
|
-
// `saasaloy add
|
|
179
|
-
// editor's autocomplete offers both and the
|
|
180
|
-
// web app's styling. Inside
|
|
181
|
-
//
|
|
182
|
-
//
|
|
177
|
+
// The signed-in apps share one primitive set in packages/ui/src/components/shell/,
|
|
178
|
+
// which `saasaloy add shell` writes (`admin` and `app` install it). Its names repeat
|
|
179
|
+
// the base ones (`button`, `card`), so an editor's autocomplete offers both and the
|
|
180
|
+
// wrong one renders with no error, in the web app's styling. Inside those apps and the
|
|
181
|
+
// shell, admin and auth folders of @repo/ui, a base primitive or a base block with a
|
|
182
|
+
// shell twin is a lint error. A project without a signed-in app has no file under
|
|
183
|
+
// these globs, so the rule never fires there.
|
|
183
184
|
{
|
|
184
185
|
files: [
|
|
185
186
|
"apps/admin/**",
|
|
187
|
+
"apps/app/**",
|
|
186
188
|
"packages/ui/src/blocks/admin/**",
|
|
187
|
-
"packages/ui/src/
|
|
188
|
-
"packages/ui/src/
|
|
189
|
+
"packages/ui/src/blocks/auth/**",
|
|
190
|
+
"packages/ui/src/blocks/shell/**",
|
|
191
|
+
"packages/ui/src/components/shell/**",
|
|
192
|
+
"packages/ui/src/containers/shell/**",
|
|
189
193
|
],
|
|
190
194
|
rules: {
|
|
191
195
|
"no-restricted-imports": [
|
|
@@ -195,12 +199,12 @@ export default defineConfig({
|
|
|
195
199
|
{
|
|
196
200
|
group: [
|
|
197
201
|
"@repo/ui/components/*",
|
|
198
|
-
"!@repo/ui/components/
|
|
202
|
+
"!@repo/ui/components/shell/*",
|
|
199
203
|
"@repo/ui/blocks/error-state",
|
|
200
204
|
"@repo/ui/blocks/theme-toggle",
|
|
201
205
|
],
|
|
202
206
|
message:
|
|
203
|
-
"
|
|
207
|
+
"Signed-in app code uses the shell set: import from @repo/ui/components/shell/* and @repo/ui/blocks/shell/*.",
|
|
204
208
|
},
|
|
205
209
|
],
|
|
206
210
|
},
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"scripts": {
|
|
12
12
|
"prepare": "husky && node packages/tooling/src/link-skills.ts",
|
|
13
13
|
"build": "turbo run build",
|
|
14
|
+
"check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build",
|
|
14
15
|
"clean": "turbo run clean && rimraf -g node_modules .turbo \"{apps,packages}/*/node_modules\" \"{apps,packages}/*/.turbo\"",
|
|
15
16
|
"deploy:production": "node packages/tooling/src/deploy-production.ts",
|
|
16
17
|
"release": "node packages/tooling/src/release.ts",
|
|
@@ -77,6 +77,39 @@ describe("createEnv", () => {
|
|
|
77
77
|
assert.match(error.message, /where mail comes from/);
|
|
78
78
|
});
|
|
79
79
|
|
|
80
|
+
// The order a capability relies on to let a provider tighten one of its keys: kv keeps
|
|
81
|
+
// its own keys in an inner preset first in `extends`, and kv-upstash appends after it.
|
|
82
|
+
it("lets a later preset in extends override an earlier one", () => {
|
|
83
|
+
const core = definePreset({
|
|
84
|
+
module: "@repo/kv",
|
|
85
|
+
server: { PREFIX: optional("") },
|
|
86
|
+
});
|
|
87
|
+
const loose = createEnv({
|
|
88
|
+
extends: [definePreset({ module: "@repo/kv", extends: [core] })],
|
|
89
|
+
});
|
|
90
|
+
assert.equal(loose({ PREFIX: "" }).PREFIX, "");
|
|
91
|
+
|
|
92
|
+
const strict = createEnv({
|
|
93
|
+
extends: [
|
|
94
|
+
definePreset({
|
|
95
|
+
module: "@repo/kv",
|
|
96
|
+
extends: [
|
|
97
|
+
core,
|
|
98
|
+
definePreset({
|
|
99
|
+
module: "kv-upstash",
|
|
100
|
+
server: { PREFIX: required() },
|
|
101
|
+
}),
|
|
102
|
+
],
|
|
103
|
+
}),
|
|
104
|
+
],
|
|
105
|
+
});
|
|
106
|
+
const error = caught(() => strict({ PREFIX: "" }));
|
|
107
|
+
assert.deepEqual(
|
|
108
|
+
error.issues.map((issue) => [issue.key, issue.module, issue.reason]),
|
|
109
|
+
[["PREFIX", "kv-upstash", "unset"]]
|
|
110
|
+
);
|
|
111
|
+
});
|
|
112
|
+
|
|
80
113
|
it("treats an empty string as unset by default", () => {
|
|
81
114
|
const env = createEnv({ server: { A: required() } });
|
|
82
115
|
const error = caught(() => env({ A: "" }));
|