Current State
DESIGN.md currently explains Sistent’s design and visual style, but it doesn’t provide enough clear and reliable guidance for AI coding agents.
Some parts are outdated or unclear, for example:
- Some spacing and border-radius details don’t match the current theme implementation.
- Some design concepts can map to multiple theme paths without clearly stating which one should be preferred.
- There is no clear distinction between canonical tokens and older or component-specific ones.
- Guidance around component usage, interaction states, responsive design, accessibility, and permissions is limited.
- Some design and implementation guidance overlaps with what is already covered in
AGENTS.md.
Desired State
DESIGN.md should become a clear and reliable design guide for both human contributors and AI coding agents.
It should:
- Clearly document Sistent’s current design tokens and how they map to the actual code.
- Clearly identify which tokens and theme paths should be preferred for new code.
- Provide simple guidance for using Sistent components, UI states, responsive layouts, accessibility, and permissions.
- Include a few common implementation examples that follow the actual Sistent conventions.
- Give AI agents clear rules to avoid inventing theme paths, colors, spacing, or component patterns.
- Keep repository, build, testing, and release guidance in
AGENTS.md instead of duplicating it here.
- Keep the document concise, accurate, and easy to maintain as the codebase changes.
Current State
DESIGN.mdcurrently explains Sistent’s design and visual style, but it doesn’t provide enough clear and reliable guidance for AI coding agents.Some parts are outdated or unclear, for example:
AGENTS.md.Desired State
DESIGN.mdshould become a clear and reliable design guide for both human contributors and AI coding agents.It should:
AGENTS.mdinstead of duplicating it here.Contributor Guides and Resources