From 51cb3147472f9d67fb4f63fbc83f141e15a6dd7e Mon Sep 17 00:00:00 2001 From: George Dulishkovych Date: Tue, 23 Jun 2026 10:31:47 +0300 Subject: [PATCH 1/4] Add .picasso/ v2 rules and absolute-URL llms.txt index Optimize the LLM index and .picasso/ rules for AI agents (PF-1997). - llms.txt links are now absolute URLs via LLM_DOCS_BASE_URL (default the production gh-pages URL, env-overridable for PR previews), so the index resolves from anywhere without a local copy. - Add canonical .picasso/ v2 rules built around fetch-on-demand from the hosted index instead of vendoring the ~1 MB doc tree, with a changelog vs v1 and removal of v1's stale patterns/tokens/96-docs pointers. Co-Authored-By: Claude Opus 4.8 (1M context) --- .picasso/CHANGELOG.md | 43 +++++++++++++++++ .picasso/README.md | 35 ++++++++++++++ .picasso/rules.md | 77 +++++++++++++++++++++++++++++++ bin/doc-gen/markdown-renderer.mjs | 23 +++++++-- 4 files changed, 173 insertions(+), 5 deletions(-) create mode 100644 .picasso/CHANGELOG.md create mode 100644 .picasso/README.md create mode 100644 .picasso/rules.md diff --git a/.picasso/CHANGELOG.md b/.picasso/CHANGELOG.md new file mode 100644 index 0000000000..d7f1bed65c --- /dev/null +++ b/.picasso/CHANGELOG.md @@ -0,0 +1,43 @@ +# Picasso agent rules — changelog + +## v2 — 2026-06-22 + +Optimizes the LLM index and `.picasso/` rules for AI agents ([PF-1997]). + +### Changed + +- **Docs are fetched on demand, not vendored.** v1 told agents to read a local + `docs/picasso/` copy of the full doc tree (~1 MB, ~96 files) committed into the + consumer repo. v2 points agents at the hosted index + () and has them fetch only + the component pages a task needs. Consumers no longer carry the tree. +- **`llms.txt` links are now absolute URLs**, so the index resolves from anywhere + (a rule file, a chat, another repo) without a local copy. Driven by the + generator's `LLM_DOCS_BASE_URL` (default: the production gh-pages URL; + env-overridable for PR-preview deployments). +- **Removed stale / broken pointers.** v1 referenced `docs/picasso/patterns/` and + `docs/picasso/tokens/`, plus a hardcoded "96 component docs" count — paths and + counts the generator does not actually produce. v2 defers the authoritative + list to the hosted index instead of duplicating (and drifting from) it. +- **Single canonical source.** v1 existed only as tool-specific copies vendored + into a consumer repo (`.cursor/rules/`, `.agents/rules/`), which had already + drifted apart. v2's canonical rules live here in the Picasso repo. + +### Not in this version (tracked separately) + +- Per-doc size trimming: collapsing the `as`-prop type union, deduping repeated + boilerplate props, slimming inlined examples. +- top-20 component scoping, pattern docs ([PF-1999]), tokens/patterns generation, + and the npm / distribution channel ([PF-2002], [PF-2003]). + +## v1 — Phase 0 + +- Storybook → markdown parser produced `llms.txt` and per-component docs, + published to gh-pages. +- Hand-written `picasso-ui-kit` rules, adopted by copying the full doc tree into + `top-assessment-frontend` (`docs/picasso/`, PR #96). + +[PF-1997]: https://toptal-core.atlassian.net/browse/PF-1997 +[PF-1999]: https://toptal-core.atlassian.net/browse/PF-1999 +[PF-2002]: https://toptal-core.atlassian.net/browse/PF-2002 +[PF-2003]: https://toptal-core.atlassian.net/browse/PF-2003 diff --git a/.picasso/README.md b/.picasso/README.md new file mode 100644 index 0000000000..831802a2f6 --- /dev/null +++ b/.picasso/README.md @@ -0,0 +1,35 @@ +# `.picasso/` — Picasso Agent Experience rules + +Canonical rules that help AI coding agents (Cursor, Claude Code, …) generate +correct application code with the Picasso design system. This is the +single source of truth; consumer repos reference it rather than hand-maintaining +their own copy. + +- **`rules.md`** — the rules: how to look up docs, package imports, and mandatory + usage rules. Kept small; it points to the hosted docs for anything volatile. +- **`CHANGELOG.md`** — what changed between rule versions. + +## How docs are served + +Component documentation is generated from Picasso's Storybook +(`pnpm generate:llm-docs`) and **served** (not vendored) alongside Storybook on +GitHub Pages: + +- Index: +- Per component: `https://toptal.github.io/picasso/llm-docs/components/.md` +- Tutorials: `https://toptal.github.io/picasso/llm-docs/tutorials/.md` + +Agents fetch the index, then the specific pages a task needs. This replaces v1's +model of copying the entire ~1 MB doc tree into each consumer repo. + +## Adopting in a consumer repo + +Point your agent tooling at `rules.md`: + +- **Cursor** — reference it from `.cursor/rules/` (or `.cursorrules`). +- **Claude Code** — reference it from `CLAUDE.md` / `AGENTS.md`. + +A packaged, versioned distribution (so updates propagate without copy-paste) is +tracked separately ([PF-2003]); until then, reference or copy `rules.md`. + +[PF-2003]: https://toptal-core.atlassian.net/browse/PF-2003 diff --git a/.picasso/rules.md b/.picasso/rules.md new file mode 100644 index 0000000000..bab06636d1 --- /dev/null +++ b/.picasso/rules.md @@ -0,0 +1,77 @@ +# Picasso UI Kit — agent rules (v2) + +Rules for AI agents writing application code that **consumes** Toptal's Picasso +design system (`@toptal/picasso*`). This file stays small on purpose: it carries +the stable, high-value rules inline and points to the hosted, always-current +docs for everything else. + +## Documentation lookup (fetch on demand) + +Component docs are **hosted** — do not vendor them into the repo. Before using an +unfamiliar Picasso component, fetch the docs on demand: + +1. Fetch the index: — every + component and tutorial is linked as an absolute URL with a one-line summary. +2. From the index, fetch the specific component page you need, e.g. + (props, + variants, examples). +3. For layout, forms, spacing, or SSR questions, fetch the relevant guide from + the index's **Tutorials** section. + +Fetch only what the task needs. If your runtime cannot reach the network, fetch +the index plus the specific component pages once and cache them for the session — +still preferred over committing the whole tree. + +## Package imports + +| Package | Import for | Example | +| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------- | +| `@toptal/picasso` | UI components and icons | `import { Button, Container, Modal, More16 } from '@toptal/picasso'` | +| `@toptal/picasso/utils` | utilities, hooks, spacing constants | `import { useNotifications } from '@toptal/picasso/utils'` | +| `@toptal/picasso-forms` | Final Form-based form components | `import { Form, Input, Select } from '@toptal/picasso-forms'` | +| `@toptal/picasso-provider` | root provider only | `import Picasso from '@toptal/picasso-provider'` | +| `@toptal/picasso-tailwind-merge` | merging Tailwind classes | `import { twMerge } from '@toptal/picasso-tailwind-merge'` | + +Import from package barrels, never deep paths. + +## Mandatory rules + +1. **Use Picasso components, not raw HTML, for UI** — no raw `