[Docs] Make DESIGN.md an AI-ready Sistent design contract
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 137
- Forks
- 239
- Avg merge
- 4d 14h
- Merged PRs (30d)
- 5
Description
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.mdinstead of duplicating it here. - Keep the document concise, accurate, and easy to maintain as the codebase changes.
Contributor Guides and Resources
- 📚 Instructions for contributing to documentation
- 🛠 Meshery Build & Release Strategy
- 🎨Wireframes and designs for Sistent site in Figma (open invite)
- 🙋🏾🙋🏼 Questions: Layer5 Discussion Forum and Layer5 Community Slack
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.
Research direction
Start by reading DESIGN.md and AGENTS.md, then compare the documented tokens and theme paths with the current Sistent implementation and component conventions. Done means DESIGN.md accurately covers preferred tokens, component usage, states, responsive design, accessibility, permissions, and examples without duplicating repository, build, testing, or release guidance.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- design, documentation, frontend
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100