From 7c0ea83d32afa8e28618036b7a853db9fcc71c4d Mon Sep 17 00:00:00 2001 From: Alexander Aidun Date: Thu, 8 Oct 2026 12:35:02 -0400 Subject: [PATCH 1/3] docs: explain team design systems --- content/(concepts)/design-system.mdx | 37 ++++++++++++++++++++++++ content/(concepts)/meta.ts | 2 +- content/(concepts)/teams.mdx | 2 ++ content/agents/index.mdx | 2 ++ styles/Spacefast/spelling-exceptions.txt | 1 + 5 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 content/(concepts)/design-system.mdx diff --git a/content/(concepts)/design-system.mdx b/content/(concepts)/design-system.mdx new file mode 100644 index 00000000..3fcdb8b6 --- /dev/null +++ b/content/(concepts)/design-system.mdx @@ -0,0 +1,37 @@ +--- +title: Design System +description: Save a team's colors, type, voice, and brand files, then apply them to a project with your agent +--- + +Save your team's design rules once, then give your agent the same starting point for each project. A saved Design System is team wide. It does not change a Space or publish a site by itself. + +## Start a Design System + +When Design System is enabled for your team, open the team and choose **Design System**. If the page is empty, you can start in either of these ways: + +- **Import what you already have.** Choose **Copy prompt** and give it to an agent connected to [Spacefast MCP](/agents). The prompt names your team and asks the agent to use `import-design-system`. Give the agent the source material too, such as a brand guide, Figma file, or repository. Ask it to report what it saved and what it could not import. +- **Start from a kit.** Choose **shadcn/ui**, **Tailwind CSS**, or **Spacefast default**. The kit saves editable colors, type, and layout values. Review them before applying them to a project. + +You can also add the standards yourself in the dashboard. **Look & feel** holds named colors, heading and body type, and layout dimensions. **Voice** holds a tone description and writing rules with optional examples. + +## Add brand files + +Use **Brand files** to upload logos, images, fonts, source documents, and other supported reference files. Each file can have a category, usage instructions, and alt text. Keep the original file and describe where your agent should use it; a filename alone cannot explain that. + +Each upload must be no larger than 25 MB. Files stay in the team's private Media Library and are downloaded through an authenticated request. A private file URL is not a public URL for a visitor-facing logo. Your agent needs to place any visitor-facing asset in the project's source before publishing. + +Uploading a file does not apply it to a Space. The agent can read the saved file and its instructions when you ask it to work on a project. + +## Apply it to a project + +On a saved Design System, choose **Apply with your agent → Copy prompt**. Give the prompt to your connected agent along with the project you want to change. The prompt asks it to read the current team standards, fetch the relevant files, apply them to the project, and check the result. + +For an existing project, tell the agent which Space or source checkout to use. It should compare the saved standards with the actual components and pages, then inspect the built result at desktop and mobile sizes. If a required file is unavailable or two rules conflict, resolve that gap before treating the work as complete. + +Saving a Design System does not update existing Spaces. Ask your agent to apply changed standards to each project you want to update. Publishing follows the instruction you give for that project. + +## Change or undo a saved rule + +Edit the saved values in **Look & feel**, **Voice**, or **Brand files**. The **Changelog** shows the current revision and changes made in this session. **Revert** can undo only the latest saved change; older changes cannot be selected for undo. + +If someone saves a newer revision while you are editing, reload the saved version and reconcile your draft before saving again. A saved change to the team Design System still needs to be applied to project source to affect a site. diff --git a/content/(concepts)/meta.ts b/content/(concepts)/meta.ts index 501d4f19..c9f8cda6 100644 --- a/content/(concepts)/meta.ts +++ b/content/(concepts)/meta.ts @@ -4,5 +4,5 @@ export default defineMeta({ title: "Concepts", collapsed: false, order: 2, - pages: ["spaces", "versions", "teams"], + pages: ["spaces", "versions", "teams", "design-system"], }); diff --git a/content/(concepts)/teams.mdx b/content/(concepts)/teams.mdx index 7f209620..b25c335d 100644 --- a/content/(concepts)/teams.mdx +++ b/content/(concepts)/teams.mdx @@ -11,6 +11,8 @@ After this page you can read the role table without guessing, invite and remove A team is the thing that owns work. Spaces, custom domains, API keys, billing, and members all hang off it. Every claimed Space belongs to exactly one team, even when you are its only member, so there is no separate personal container to reason about. +A team can also hold a [Design System](/design-system) for colors, type, voice, and brand files. Saving those standards does not change any Space until you apply them to its project. + A team has a name and a slug. The slug is the first segment of its dashboard URLs and you can change it in **Team settings → General**, where a live check tells you whether the new one is free. | Slug rule | Value | diff --git a/content/agents/index.mdx b/content/agents/index.mdx index 55ecfbc0..cb220d06 100644 --- a/content/agents/index.mdx +++ b/content/agents/index.mdx @@ -17,6 +17,8 @@ Anything you can do in the dashboard, an agent can do over MCP. The Spacefast MC Inside `execute`, search for an operation with `tools.search`, read its contract with `tools.describe`, then call it. Check each write with a read before reporting success. +If your team has a saved [Design System](/design-system), your agent can read its standards and files while working on a project. Ask it to apply the system to a new build or bring an existing project into line with the current rules. + Publish this folder to Spacefast and give me the live URL. diff --git a/styles/Spacefast/spelling-exceptions.txt b/styles/Spacefast/spelling-exceptions.txt index 48251be6..5a6febe7 100644 --- a/styles/Spacefast/spelling-exceptions.txt +++ b/styles/Spacefast/spelling-exceptions.txt @@ -64,6 +64,7 @@ exif extensionless Favicon fetchable +Figma finalizer followable forwardable From f617884e601f78f5c74f29fa27bd27e688642765 Mon Sep 17 00:00:00 2001 From: Alexander Aidun Date: Thu, 8 Oct 2026 12:43:38 -0400 Subject: [PATCH 2/3] docs: align design system guide with task skills --- content/(concepts)/design-system.mdx | 26 ++++++++++++++------------ content/agents/skills.mdx | 27 ++++++++++++++++++++------- 2 files changed, 34 insertions(+), 19 deletions(-) diff --git a/content/(concepts)/design-system.mdx b/content/(concepts)/design-system.mdx index 3fcdb8b6..eca66b9c 100644 --- a/content/(concepts)/design-system.mdx +++ b/content/(concepts)/design-system.mdx @@ -3,35 +3,37 @@ title: Design System description: Save a team's colors, type, voice, and brand files, then apply them to a project with your agent --- -Save your team's design rules once, then give your agent the same starting point for each project. A saved Design System is team wide. It does not change a Space or publish a site by itself. +Your team's Design System holds colors, type, layout, voice, and brand files for agents to use across projects. Saving it does not change a Space or publish a site. ## Start a Design System -When Design System is enabled for your team, open the team and choose **Design System**. If the page is empty, you can start in either of these ways: +When Design System is enabled for your team, open the team and choose **Design System**. If you see **Set up team context**, select it first. Then choose how to start: -- **Import what you already have.** Choose **Copy prompt** and give it to an agent connected to [Spacefast MCP](/agents). The prompt names your team and asks the agent to use `import-design-system`. Give the agent the source material too, such as a brand guide, Figma file, or repository. Ask it to report what it saved and what it could not import. +- **Import what you already have.** Choose **Copy prompt** and give it to an agent connected to [Spacefast MCP](/agents). Give the agent your brand guide, Figma file, or repository too. The `import-design-system` skill saves supported values, registers source files, and keeps other guidance in supporting Memory records. Ask for a report of conflicts and anything it could not import. - **Start from a kit.** Choose **shadcn/ui**, **Tailwind CSS**, or **Spacefast default**. The kit saves editable colors, type, and layout values. Review them before applying them to a project. -You can also add the standards yourself in the dashboard. **Look & feel** holds named colors, heading and body type, and layout dimensions. **Voice** holds a tone description and writing rules with optional examples. +You can also add the standards yourself in the dashboard. **Look & feel** holds named colors, typography for headings and body text, and layout dimensions. **Voice** holds a tone description and writing rules with optional examples. ## Add brand files -Use **Brand files** to upload logos, images, fonts, source documents, and other supported reference files. Each file can have a category, usage instructions, and alt text. Keep the original file and describe where your agent should use it; a filename alone cannot explain that. +Use **Brand files** to upload logos, images, fonts, and source documents. After uploading, edit **How to use** to tell your agent where and when a file belongs. A filename alone cannot do that job. -Each upload must be no larger than 25 MB. Files stay in the team's private Media Library and are downloaded through an authenticated request. A private file URL is not a public URL for a visitor-facing logo. Your agent needs to place any visitor-facing asset in the project's source before publishing. - -Uploading a file does not apply it to a Space. The agent can read the saved file and its instructions when you ask it to work on a project. +Each upload must be no larger than 25 MB. Files stay in the team's private Media Library. Accepted SVG files are sanitized on upload, so check the saved artwork. An agent must download needed files and put visitor-facing assets in the project's source; private file URLs do not belong in a live page. ## Apply it to a project -On a saved Design System, choose **Apply with your agent → Copy prompt**. Give the prompt to your connected agent along with the project you want to change. The prompt asks it to read the current team standards, fetch the relevant files, apply them to the project, and check the result. +On a saved Design System, choose **Apply with your agent → Copy prompt**. Give the prompt to your connected agent and name the project or Space you want it to work on. The prompt points the agent to the current team standards and these skills when available: + +- `apply-design-system` builds a new project or makes a requested source edit using the saved standards. +- `verify-design-system` checks a matching source build or preview and fixes gaps when you ask for corrections. +- `update-design` brings a named existing Space or linked project into line with the current standards. -For an existing project, tell the agent which Space or source checkout to use. It should compare the saved standards with the actual components and pages, then inspect the built result at desktop and mobile sizes. If a required file is unavailable or two rules conflict, resolve that gap before treating the work as complete. +The agent reads the saved Design System and applicable Memory, works from the complete project source, and checks the built result at desktop and mobile sizes. If a required file is unavailable or two rules conflict, it should report the specific gap. -Saving a Design System does not update existing Spaces. Ask your agent to apply changed standards to each project you want to update. Publishing follows the instruction you give for that project. +Changes to team standards do not roll out to existing Spaces. Name each Space you want updated. Whether the agent publishes depends on your request and that Space's work mode. ## Change or undo a saved rule Edit the saved values in **Look & feel**, **Voice**, or **Brand files**. The **Changelog** shows the current revision and changes made in this session. **Revert** can undo only the latest saved change; older changes cannot be selected for undo. -If someone saves a newer revision while you are editing, reload the saved version and reconcile your draft before saving again. A saved change to the team Design System still needs to be applied to project source to affect a site. +If someone saves a newer revision while you are editing, reload the saved version and reconcile your draft before saving again. diff --git a/content/agents/skills.mdx b/content/agents/skills.mdx index aa281d61..3f209cbc 100644 --- a/content/agents/skills.mdx +++ b/content/agents/skills.mdx @@ -1,11 +1,11 @@ --- title: Skills -description: The Spacefast agent skill, what it tells your agent to do, and how to install or remove it with the sf CLI +description: The base Spacefast skill and the task skills for saving and using a team's Design System --- -After this page you know what the shipped skill instructs your agent to do, which clients get which variant, and how to install, check, or remove it. +The base `spacefast` skill routes publishing and management work to the right tools. Spacefast plugins also include task skills for saving and using a team's Design System. -## One skill, called `spacefast` +## The base `spacefast` skill Every lane ships a skill named `spacefast`. It is two markdown files, `SKILL.md` and `references.md`, rendered from one template into per-client variants. @@ -18,7 +18,20 @@ Every lane ships a skill named `spacefast`. It is two markdown files, `SKILL.md` The plugin lanes carry the MCP variant, which routes work to the typed tools. The copy bundled with the CLI carries the curl and HTTP API variant instead, for agents that have no MCP connection at all. Same name, same product rules, different lane. -## What triggers it +## Design System task skills + +Spacefast plugins include four skills for the [Design System](/design-system): + +| Skill | Use it for | +|---|---| +| `import-design-system` | Save supplied standards, source files, and supporting guidance to the team | +| `apply-design-system` | Use saved standards in a new build or requested source edit | +| `verify-design-system` | Check a source build or preview against current standards; fix only when you ask for corrections | +| `update-design` | Bring a named existing Space or linked project onto current standards | + +Importing standards does not change a project. Applying them to one project does not roll them out to the team's other Spaces. + +## What triggers the base skill The trigger line is the frontmatter `description`. Your client matches it against what you asked for. @@ -65,7 +78,7 @@ Publish this folder to Spacefast and give me the live URL. Show me the deployments for this Space and whether the last build passed. -## What it instructs +## What the base skill instructs The skill's job is routing and conduct. The MCP variant follows these tool choices. @@ -90,9 +103,9 @@ The rest sets behavior the tools alone do not enforce. ## Kept in sync with the tools -A CI check re-renders every skill variant and compares the tool names it mentions against the live tool list, in both directions. A tool added without a skill update fails the build, and so does a skill that names a tool which no longer exists. The skill you install always names exactly the five tools the server registers. +A CI check re-renders every skill variant and compares the tool names it mentions against the live tool list, in both directions. A tool added without a skill update fails the build, and so does a skill that names a tool which no longer exists. The base skill names exactly the five tools the server registers. -## Install it on its own +## Install the base skill on its own If you want the skill without touching MCP config, the CLI installs the copy bundled with it. From 77233efef52fde6c149c7877f26e1457a6963305 Mon Sep 17 00:00:00 2001 From: Alexander Aidun Date: Thu, 8 Oct 2026 12:46:03 -0400 Subject: [PATCH 3/3] docs: state why teams use design systems --- content/(concepts)/design-system.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/(concepts)/design-system.mdx b/content/(concepts)/design-system.mdx index eca66b9c..0a644e71 100644 --- a/content/(concepts)/design-system.mdx +++ b/content/(concepts)/design-system.mdx @@ -1,9 +1,9 @@ --- title: Design System -description: Save a team's colors, type, voice, and brand files, then apply them to a project with your agent +description: Save a team's design rules once, then reuse and check them across projects --- -Your team's Design System holds colors, type, layout, voice, and brand files for agents to use across projects. Saving it does not change a Space or publish a site. +Save your team's colors, type, layout, voice, and brand files in one Design System. A connected agent can reuse those standards in a new project, check a build against them, or bring a named Space up to date. You choose which Spaces change. Saving the system alone does not edit or publish a site. ## Start a Design System