Design a product catalogue

What a catalogue is for

The shared standard makes every Weblabor product use the same tokens and the same base components. It does not make two screens of the same product look alike: a dashboard tile built in March and its twin built in September can both follow the standard and still differ, because nothing says what a tile is in this product.

/design-catalog is your product's design lead for that level. The catalogue it plans is two things, and neither is a document:

Composed components in your product's own design layer, built on top of the base components and never duplicating them under another name, and called from every screen as <x-design::name>.
The base's design screen at /admin/design, which renders every design component in use. A screen that imports the real components cannot describe a version of them that no longer exists.

It plans, and builds nothing in your product. It creates no component, edits no screen and makes no commit there of its own. What it leaves behind are documents in your project in the toolkit: your identity manual, the plans that build the catalogue, and rows of your pending findings. The building happens in the queue. It may open your product in the browser to see what it is working on. The one thing it can change outside the toolkit is a fix in weblabor-base or weblabor-teams, and only when you say yes, along with the merge that brings that fix into your product.

Where it runs

It runs inside your product's own repository, and checks three things before anything else. When one fails it says which and stops, having written nothing:

It is not the toolkit's own repository. Start it again from your product.
The checkout is an application, with views and styles to build a catalogue in.
weblabor-base's design layer has arrived by merge. If your product last merged the base before the layer existed, merge it first and run this again.

It also needs the toolkit connected, because everything it writes lives there. And the folder your components go in has to carry your product's own name, read from config/app.php; while it still resolves to the base's or the generic one, it tells you to set your project's name first.

Your identity manual, in identity/

At the start it asks for your identity or interface manual. Give it whatever you have: the manual, your logos, a PDF or a picture of the brand, by their path on your computer, or a document or file already uploaded to your project in the Projects section, named by its path.

Everything that helps to understand the design is kept in your project's identity/ folder in the toolkit:

A Markdown document is kept as it is.
An image, a logo or a PDF is uploaded as it is, untouched, and beside it goes a written description of what it shows: the colours with their values, the typography, the spacing, the examples and the rules of use.
A file you only attached to the conversation, with no path on your computer, cannot be uploaded from there: it asks you for its path, or to upload it yourself from your project's page, and the report says which files are still waiting.
If your assistant cannot read images, it asks you for the values in words. Colours, a type scale and spacing described in words are a complete manual.

The brief for your landing — what the product is, who it is for, what it promises — is kept there too, never in your repository. When identity/ already holds documents or files, it reads them, the originals included, and only adds or updates what you gave it this time. From then on that folder is the permanent reference: the plans take their colours and font from it, and the design review in the queue judges what was built against it.

What it reads before proposing anything

It reads the whole product, not the likely parts: your design layer and what the base already ships, screens that draw by hand what a design component already renders, blocks that repeat between screens with no component behind them, components you built outside your design layer, the navigation, the signed-in frame and the admin panel, every screen grouped by area, what the product says about itself for its landing — your product vision among it — and what your analysis/ folder and your pending findings already plan or note.

A component that turns out to be the base's, and not yours, is never moved or edited by a plan. One whose origin cannot be settled is left out of every plan and named.

The proposal, as drawings you choose from

You decide the design, and a design is judged by looking at it. So the proposal is not a text to approve: it is a page shown beside the conversation, in rounds. Each round puts one of your current screens — the home of the signed-in area, say, rebuilt from the code — next to two to four proposals drawn on that same screen. The first round also tells you what it found and what it saved in identity/, so you can correct a description before anything rests on it.

The rounds go from the general to the particular: first the overall direction, then the colours of the one you chose, then the structure of the menu and the frame. The first round always runs; a later one your identity manual already answers is skipped, and a choice that leaves a doubt opens another round.
What you choose applies to everything. Choose rounded corners once and every component has them; nothing is asked screen by screen.
A redesign has to show. Beside colours and components, the proposals rebuild the frame: the menu, the sidebars, the signed-in area and the admin panel.
Every area gets the same treatment. If one gets less, the drawing says so, with the reason.

The ux-designer agent proposes what is drawn, and the smallest set of components your product needs: variants of one pattern become one component wherever a setting can absorb the difference. You only decide what you see. Which components, how the plans are split and everything else technical is decided for you, and no plan is shown to you for approval. The one decision that is not a drawing is about a fix in a base, below; besides that, it only asks for what it cannot find itself, such as your manual's files or which thread runs the queue. Drawings are only for deciding the design: everything else it tells you — a notice, its report, that question about a fix in a base — comes as ordinary text.

The plans it writes

Each plan has the shape of a plan from /plan-prompt, opens with the line Origen: escrito por /design-catalog., and is saved in your project's analysis/ folder as Ready to run. They are split so the queue can build them side by side:

A base plan: your colours and font, and the frame — the menu, the sidebars, the signed-in area and the admin panel.
One plan per family of components, and one for the landing, each resting on the base plan. Every screen belongs to just one of them, so two plans never touch the same file.
A last plan that walks every screen in your browser at 375, 768 and 1440 pixels wide, resting on all the others.

Your primary colour, accent and font go in your product's theme file, resources/css/themes/your-project.css, as the brand variables weblabor-base's Brand and interface guide describes — with the import of your font when it has to be loaded, and no styles of their own; everything else about the look lives in the components. Every screen is a point of its plan, with its own checklist row. A screen left out of every plan is named in the report, with why. Each plan's proof opens /admin/design and every screen it touches, because a restyle that dropped a setting shows only as something missing on screen.

Nothing is written into your repository, and nothing is committed there. The run ends by naming the plans and pointing you at /next.

How the queue builds them

/next builds each plan, checks it in the browser with /test, and then has ux-designer open the screens it built and judge them against your catalogue and your identity manual. When they do not follow both, the designer's correction is written into the same plan, which the queue builds and reviews again, within the same three attempts as any other check. That review is described in Run the queue with /next.

It follows the queue until the end

Saving the plans is not the end. It schedules a coordinator — the same one /coordinate sets up, following the same rule — which every 20 minutes checks the thread where /next runs, by default the one named Next steps: that it is working, that a plan of its own is not stuck on questions — which it answers from what you chose in the rounds, asking you, with drawings, only what those choices leave open about the design, and deciding anything technical itself — and that no new document was missed, which it tells that thread about. If there is no thread with that name, it asks you which one to watch. It never builds and never runs /next itself. It stops once all its plans are implemented or stopped where only you can move them — rejected, paused, blocked after three attempts, or waiting on a question for you — and nothing else is on its way. If your assistant cannot schedule this, it tells you and asks you to write to it every so often so it can check.

A fix that belongs to a base

If it finds something that is fixed in weblabor-base or weblabor-teams rather than in your product, it asks you: this is what we found, it is fixed from that project, shall we? If you say yes, it fixes it directly there, with a commit of its own holding only that fix. It does not push it: pushing it is yours. When the fix is in the repository your product merges from directly, the coordinator then brings it onto your product's base-update branch and merges that into the branch your product's plans were saved on, the same path you take by hand. It only ever moves base-update forward: if that branch has commits the base does not, it tells you and waits. It does not wait for plans the queue builds in their own worktrees, only for one built directly on the branch, in your product or in the base, and for a plan your product's queue is checking in the browser. Your product needs that base-update branch: if it has none, /design-catalog tells you when it sets the coordinator up, and the fix waits until you create it. The coordinator leaves it to you, with the file and the reason, when a conflict cannot be resolved with certainty. A fix made higher up the chain is yours to bring down. The rest carries on: the plans that need it wait for that behavior on their own, and it tells you once the fix is in the base.

Running it again

Once your product has a catalogue, this is the run that happens most: screens built since then drift from it, or grow patterns it does not cover. A later run reviews every screen against the catalogue and identity/, in both directions — patterns no component covers, and components a screen ignored, or a colour, type or spacing that strays from the manual. What does not comply becomes a correction plan; what is newly needed becomes a new plan. Both go through the same rounds.

Components that could serve every product

A component that depends on nothing about your product — not its brand, not its domain — is a candidate for weblabor-base. It is written as a row in your project's Pending findings, naming the screens it serves, so the signal outlives the conversation. The row goes once your product adopts the base's version. A restyle of a base component is never a candidate.

What it will not do

Change the shared Tailwind standard. It is one standard for every product; to change it, use /improve-toolkit.
Edit files the base keeps for itself, or weblabor-base itself, except a fix you approved. A product changes the base's look with a same-name copy in its own design layer, and its colours and font in its own theme file.
Tidy the project in general. That is /cleanup.

Run the queue with /next — how the plans are built and reviewed for design.
Write the product vision — what the landing copy is read from.
What the analyzer cannot check — reusing a component, one of the checks no single file proves.