Skip to content

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

Description

@PARTH-TUSSLE

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions