mittwald / mittwald/flow

Agent docs only help people who build Flow, not people who use it

Open
#2,867 0 comments 0 reactions 1 assignee View on GitHub

@maaaathis is already working on this.

Since Aug 24, 2026.

documentation to-discuss
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.md links ../../AGENTS.md and ../../docs/remote-ui.md.
    Inside node_modules both are dead ends.
  • dist/assets/doc-properties.json is 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.