Backbase

Skills and commands

The whole plugin on one map. Point at a skill to see what it does and the bb commands it runs.

  1. 1Start a site

  2. Gate 1plan

  3. 2Write to the space

  4. Gate 2sync plan

  5. 3Build the page

  6. Pushpush plan

  7. 4Change the page

  8. Pushpush plan↺ again
  9. loaded by compose, edit, refine

bbthe 38 commands the skills run

  • a slash command loads it
  • a skill loads it
  • loads
  • you approve
  • bb commands it runs

After the page

The component stage fills the planned slots. A built component can already go to Backpack with upstream.

A command loads a skill, and the agent follows it. Every write waits at a gate for your yes; nothing writes to Figma or publishes.

Skills at a glance

SkillWhat it doesUse it when
new/backbase:newStart a new Backpack site from an empty folder and a Figma frame link.You have a Figma frame and no project yet.
analyze/backbase:analyzeTurn a Figma frame into a section plan for a Backpack project, reusing Site Builder bloks first, and stop at Gate 1 for the person to confirm.You have a project and a Figma frame to build in it.
read-figmaRead a Figma frame through the person's own Figma MCP and distil it into a validated sections.json, part by part.A flow needs the frame's parts; analyze loads it.
classifyDecide how to build each part of a Figma frame in a Backpack project, as reuse, compose, create, wrap, global or unsure, and write plan.json.sections.json and the catalog are ready; analyze loads it.
sync-space/backbase:syncBring a Backpack project's Storyblok space up to date with its code at Gate 2.After Gate 1, before the first compose, or when the project's schemas change.
compose/backbase:composeTurn an approved Backbase plan into a draft Storyblok story, validate it, and push it with bb story push once the person approves the push plan, never published.The plan passed Gate 1 and the space passed Gate 2: build the page.
opsChange a local Backbase story only through ops.Compose, edit or refine changes a story; they load it.
refine/backbase:refineAudit a composed Backbase story against its Figma frame by measurement and a section-by-section visual review, then push it once.After compose, to bring the page closer to the frame by measurement.
edit/backbase:editChange a story that's already in the project's Storyblok space, section by section.A page is in your space, and you want part of it changed.
outputHow every Backbase skill talks to the person.Every skill that talks to you loads it: three layers, plain words, about 150 words.
component/backbase:componentBuild the missing Wrap or Create components reserved by a Backbase story's slots, check them, sync approved schemas at Gate 2, replace slots through ops, measure and push one draft after approval.Compose or refine left slots: build the missing components.
upstream/backbase:upstreamThe one road to GCS, who make Backpack and Site Builder, in ef-global/backpack.You built a Wrap or a Create, and Backpack should have it, or the plan has design requests for GCS.

All skills in detail

ShowHide the cards

Each card’s bb chips are the commands the skill runs, from its SKILL.md, linked to the reference.

Generated from the plugin's SKILL.md files and commands when the site was built: 12 skills, 8 commands.

Start a site

backbase-new

/backbase:new

Start a new Backpack site from an empty folder and a Figma frame link.

Use it when
You have a Figma frame and no project yet.
Stops at
Gate 1
Reads
  • The Figma frame, through your Figma connector
Writes
  • A new project from the boilerplate
  • .backbase/config.json
  • .backbase/plan.json
Loads
backbase-output, backbase-analyze
bb

backbase-analyze

/backbase:analyze

Turn a Figma frame into a section plan for a Backpack project, reusing Site Builder bloks first, and stop at Gate 1 for the person to confirm.

Use it when
You have a project and a Figma frame to build in it.
Stops at
Gate 1
Reads
  • The Figma frame, through your Figma connector
  • The project's Backpack and schemas
  • The space's presets, read-only
Writes
  • .backbase/figma/<node-id>/sections.json
  • .backbase/catalog.json
  • .backbase/space-presets.json, when it reads the space
  • .backbase/knowledge.md
  • .backbase/plan.json
Loads
backbase-output, backbase-read-figma, backbase-classify
bb

backbase-read-figma

loaded by analyze

Read a Figma frame through the person's own Figma MCP and distil it into a validated sections.json, part by part.

Use it when
A flow needs the frame's parts; analyze loads it.
Stops at
No gate
Reads
  • The Figma frame, through your Figma connector
Writes
  • .backbase/figma/<node-id>/sections.json
  • .backbase/figma/*/images/
bb

backbase-classify

loaded by analyze

Decide how to build each part of a Figma frame in a Backpack project, as reuse, compose, create, wrap, global or unsure, and write plan.json.

Use it when
sections.json and the catalog are ready; analyze loads it.
Stops at
No gate
Reads
  • The frame's sections, from read-figma
  • .backbase/catalog.json
  • .backbase/knowledge.md
Writes
  • .backbase/plan.json
bb

backbase-output

loaded by analyze, component, compose, edit, new, refine, sync-space, upstream

How every Backbase skill talks to the person.

Use it when
Every skill that talks to you loads it: three layers, plain words, about 150 words.
Stops at
No gate
Reads
  • What the skill that loads it found
Writes
  • .backbase/report.html, bb report's page, which each message links
  • .backbase/reports/<moment>.md, the detail the page doesn't draw
bb

Write to the space

backbase-sync-space

/backbase:sync

Bring a Backpack project's Storyblok space up to date with its code at Gate 2.

Use it when
After Gate 1, before the first compose, or when the project's schemas change.
Stops at
Gate 2
Reads
  • The project's components and datasources
  • .backbase/plan.json
  • .backbase/figma/<node-id>/sections.json, for the palette
  • Storyblok: the space's colour datasources, field plugins and Settings story
Writes
  • .backbase/space-plan.json
  • .backbase/space-sync.json
  • Storyblok: the components, datasources and theme you approve
  • Storyblok: the Settings story's theme, as a draft, never published
Loads
backbase-output
bb

Build the page

backbase-compose

/backbase:compose

Turn an approved Backbase plan into a draft Storyblok story, validate it, and push it with bb story push once the person approves the push plan, never published.

Use it when
The plan passed Gate 1 and the space passed Gate 2: build the page.
Stops at
Push approval
Reads
  • .backbase/plan.json
  • .backbase/figma/<node-id>/sections.json
  • .backbase/catalog.json
  • .backbase/knowledge.md
Writes
  • .backbase/catalog.json, again when it's stale
  • .backbase/knowledge.md, again when it's stale
  • .backbase/stories/<slug>.json
  • Storyblok: the images you approve, and the story as a draft
Loads
backbase-output, backbase-ops
bb

Change the page

backbase-refine

/backbase:refine

Audit a composed Backbase story against its Figma frame by measurement and a section-by-section visual review, then push it once.

Use it when
After compose, to bring the page closer to the frame by measurement.
Stops at
Push approval
Reads
  • .backbase/stories/<slug>.json
  • .backbase/plan.json
  • .backbase/knowledge.md
  • The page, rendered locally
Writes
  • .backbase/catalog.json, again when it's stale
  • .backbase/knowledge.md, again when it's stale
  • .backbase/stories/<slug>.json
  • .backbase/compare/<slug>/iterations/<n>/
  • Storyblok: the story once, as a draft
Loads
backbase-output, backbase-ops
bb

backbase-edit

/backbase:edit

Change a story that's already in the project's Storyblok space, section by section.

Use it when
A page is in your space, and you want part of it changed.
Stops at
Push approval
Reads
  • Storyblok: the story as it is now
  • .backbase/catalog.json
  • .backbase/knowledge.md
Writes
  • .backbase/catalog.json, again when it's stale
  • .backbase/knowledge.md, again when it's stale
  • .backbase/stories/<slug>.json
  • .backbase/stories/<slug>.remote.json
  • .backbase/edits/<slug>/images.json and .backbase/assets.json, for a new image
  • Storyblok: the images you approve, then that story, as a draft
Loads
backbase-output, backbase-ops
bb

backbase-component

/backbase:component

Build the missing Wrap or Create components reserved by a Backbase story's slots, check them, sync approved schemas at Gate 2, replace slots through ops, measure and push one draft after approval.

Use it when
Compose or refine left slots: build the missing components.
Stops at
No gate
Reads
  • The local story and approved plan
  • Installed Backpack declarations and saved Figma layers
Writes
  • Local component code and schemas
  • Storyblok: approved components and one approved draft story
Loads
backbase-ops, backbase-output
bb

backbase-upstream

/backbase:upstream

The one road to GCS, who make Backpack and Site Builder, in ef-global/backpack.

Use it when
You built a Wrap or a Create, and Backpack should have it, or the plan has design requests for GCS.
Stops at
No gate
Reads
  • The local component in src/components/
  • A fresh clone of ef-global/backpack, in a temp folder
  • .backbase/plan.json
  • .backbase/requests/design-gaps.md
  • Open issues in ef-global/backpack, read-only
  • .backbase/figma/<node-id>/shots/
Writes
  • .backbase/upstream/<kebab>/issue.md
  • .backbase/upstream/<kebab>/pr.md
  • .backbase/requests/open-issues.json
  • .backbase/requests/<key>.issue.md or .comment.md
  • GitHub: an issue in ef-global/backpack, then a draft pull request, each after your yes
  • GitHub: each design request as an issue, or a comment on an open one, after your yes
Loads
backbase-output
bb

The commands

ShowHide the table
CommandLoadsWhat it does
/backbase:analyze<figma-url>[--project <dir>][--space <space-id>]backbase-analyzeAnalyse a Figma frame and plan it as Backpack bloks, then stop at Gate 1.
/backbase:component[<story-file>][--project <dir>]backbase-componentBuild the missing components in a story's slots, sync approved schemas at Gate 2, replace slots through ops, measure and push one draft after approval.
/backbase:compose[--project <dir>][--slug <slug>]backbase-composeTurn the plan approved at Gate 1 into a draft Storyblok story, validated, then pushed by bb once you approve the push plan, never published.
/backbase:edit[<story id or full path>]<what to change>[--project <dir>]backbase-editChange a story in your Storyblok space, section by section, from what Storyblok has now. Only the sections you ask for change, and you see the diff and the push plan before it's pushed as a draft, never published.
/backbase:new<figma-url>[folder][--space <id>]backbase-newStart a new site from an empty folder and a Figma frame, from bb doctor to a plan at Gate 1.
/backbase:refine[slug][--project <dir>][--tries <n>][--budget <n>][--fit-drop <fit>][--sections <n> (deprecated)]backbase-refineAudit a composed story against the Figma frame by measurement, rendered locally, keep what moves each delta toward the frame, then push it once you approve the push plan.
/backbase:sync[--project <dir>]backbase-sync-spaceSync the project's components and datasources to its Storyblok space at Gate 2, writing only the plan the person approves.
/backbase:upstream[<component> | requests][--project <dir>]backbase-upstreamThe one road to GCS in ef-global/backpack. Take a local Wrap or Create there as an issue, then a draft pull request in Backpack's conventions, or file the plan's design requests as issues, or as comments on open issues that have them. Each only after the person's yes.

Where the knowledge comes from

ShowHide where it comes from

The knowledge pack, .backbase/knowledge.md, is what the agent reads to choose bloks and write design values. bb catalog --knowledge compiles it from your project as it is, not from a copy in bb. Two parts are different: the field → CSS table, and the house style.

WhatWhere it comes fromYour project's?
Bloks: fields, option sets, allowed children, design subfields, presetsThe Backpack installed in node_modules/@ef-global/backpack, at its version: its compiled .sb.cjs schemas, .presets.cjs presets and.d.ts types. Backpack 4 only.Yes
The project's local Wraps and CreatesIts .sb.ts, .sb.cjs, .sb.mjs and.sb.js schemas in storyblok.config'scomponentsDirectories (src and storyblok without one), and its component-list.ts, wherever it is in the project. Its resolvers and backbase.placements.json change the allowed children.Yes
Colour tokensBackpack's .sb.datasource.cjs datasources and the project's own, in the same folders as its schemas, mapped to the frame's colour variables whensections.json is given.Yes
Space presets.backbase/space-presets.json, when the space was read.Yes
Field → CSS: what each design value renders.backbase/render-semantics.json when it's for the installed version, else the table bb ships for that version (today 4.11.0 only), else none, with a warning.For its version, if there's a table
House styleBundled in bb: mined from Backpack 4.11.0's presets, plus curated rulings.No: the same everywhere

The pack and the catalog record what they were compiled from. After you update Backpack or change a schema, compose, edit and refine rebuild them first with --if-stale, and tell you in one line. A stale catalog is never used: a command refuses it with catalog-stale. See When the catalog goes stale.

Custom-component flow

A component Backpack lacks gets a slot on the page, and /backbase:component builds it.

More

A Wrap gives Backpack’s existing React a local Storyblok version; a Create adds new React, almost always from Backpack’s primitives, with your yes. Both need evidence at Gate 1 of what was tried. Compose leaves a slot for each, a dashed box in dev and drafts that renders nothing in published content, and /backbase:component builds them after an approved sync. Refine skips slots, and can suggest one after two stuck rounds, with your yes. /backbase:upstream can then take one to Backpack, with a yes for its issue and another for its draft pull request.

From a planned gap to a measured component.Point at a step, tab to it, or tap to open its details. Click to keep them open; Esc closes them.

  1. 1Plan the gap

    1. AgentClassifyWrap or Create, with evidence

      Show what was tried: catalog components, presets and why each failed. Wrap uses React Backpack already exports; Create needs new React, almost always from Backpack primitives.

    2. YouGate 1You approve the component

      Approve each Wrap and Create with its evidence and planned slot. An unanswered question stays open; the agent never assumes approval.

    3. AgentLeave a slotCompose leaves it; refine skips it

      The slot blok shows a dashed placeholder in dev and drafts and renders nothing in published production content. Refine skips slots and can suggest one after two stuck rounds, with approval. The last component stage fills it.

  2. 2Build it locally

    /backbase:component

    1. bb / checksGenerate, then mapbb component new

      The generator writes the wrapper, schema, map entry, placements, resolver and design field. The agent writes the props mapping and schema content fields; a Create also gets React from Backpack primitives. Restate an approved Wrap; ask again for each Create.

    2. bb / checksChaperoneFix until green; refresh the catalog

      Fix until green. Also run tsc and the project's build or lint, then refresh bb catalog. Never baseline new violations.

      • Schema name matches file and folder; adjacent wrapper exports the right name.
      • Registered in the component map and placeable in a parent.
      • Backpack imports; no deep imports or copied styles/source.
      • No Backpack shadowing or local sb- prefix.
      • Flex children have Backpack's design field and options.
      • No rival UI libraries or raw interactive HTML.
    3. YouGate 2Sync components, never --ssot

      Show bb space plan --components-only once for all the new components. Sync only the components you approve with bb space sync --components-only; never --ssot and never delete components from the space.

    4. bb / checksReplace the slotOne ops envelope, same index

      Remove the slot and insert the new blok at the same index, using Figma's content. Handle images, materialize design values, then validate and stamp. Never edit the story file by hand.

    5. bb / checksMeasureCompare the filled sections

      Serve the local story, then run bb page measure and bb page compare on the filled sections. Refine within the usual limits before proposing a push.

    6. YouPush a draftOne push plan, after your yes

      Show the story push plan and wait for approval. Push once at the end as a draft; nothing publishes.

  3. 3Optional: send to Backpack

    /backbase:upstream

    1. YouApprove the issueFirst approval → file in Backpack

      Only if you ask for upstream: the agent drafts the issue with evidence and a screenshot, shows it, and files it in ef-global/backpack after your yes.

    2. YouApprove the draft PRSecond approval → push and open

      Work in a fresh temporary Backpack clone, following its conventions and checks. Show the diff, then wait for a separate yes before pushing and opening a draft PR. Never merge or release. Keep the local component until Backpack releases it.

Agent makes the judgment calls. bb and Chaperone check and write. You approve at the gates.

What’s coming

Other ways to use Backbase still need diagrams:

  • a new site in a new repo;
  • editing an existing site and repo;
  • migrating a site;
  • editing only a Site Builder part of a site.