layer5io / layer5io/sistent

[Docs] Make DESIGN.md an AI-ready Sistent design contract

Open
#1,837 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/docs language/markdown
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.md instead of duplicating it here.
  • Keep the document concise, accurate, and easy to maintain as the codebase changes.
Contributor Guides and Resources

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.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.