Agent docs only help people who build Flow, not people who use it
@maaaathis is already working on this.
Since Aug 24, 2026.
- Dominant language
- TypeScript
- Stars
- 15
- Forks
- 3
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 184
Description
Problem
All agent guidance in this project is contributor-facing. Root AGENTS.md, the
per-package guides, and the AGENTS.md + PATTERNS.md shipped in
@mittwald/flow-react-components describe how to build a component inside
Flow: component anatomy, the flowComponent factory, PropsContext, generated
code, the testing bar, nx targets, conventional commits.
Nothing describes how to build an app with Flow. An agent in a consumer or
extension project gets no answer to: which component covers this use case,
which tokens exist and that raw values are not an option, how spacing and
layout are meant to be composed, which styleguide pattern applies here.
So it falls back to generic React and the result ignores the principles the
styleguide documents. Pasting links into every prompt fixes the symptom, not
the cause.
Gaps found while checking:
- The styleguide content (Foundations, Patterns, guidelines) lives in
apps/docs, which is private. It ships nowhere. - The shipped
AGENTS.mdlinks../../AGENTS.mdand../../docs/remote-ui.md.
Insidenode_modulesboth are dead ends. dist/assets/doc-properties.jsonis 13 MB with no index. Not readable as-is.
Possible steps
- Add a consumer-facing agent guide to the package, separate from the
contributor one: component selection, tokens, layout and spacing rules,
the styleguide patterns, common mistakes - Fix the relative links in the shipped
AGENTS.md, or make them absolute - Publish an ESLint config for consumers: flag raw values where tokens
exist, custom layout CSS on Flow components, invalid nesting. Lint output
reaches the agent whether it read anything or not - Ship a compact, indexed version of the prop data next to the 13 MB file
- Longer term: a Flow MCP server for components, tokens and patterns
Why
We support agents that change Flow far better than agents that use it. For a
design system that ratio should be the other way round. The investment already
exists (AGENTS.md in nearly every package, .claude/commands, 184 documented
patterns), it just stops at the package boundary.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.