From 0584ce7b53cf343e6d587321ef83cd47ba7e5274 Mon Sep 17 00:00:00 2001 From: njg7194 Date: Sun, 1 Feb 2026 13:22:30 +0900 Subject: [PATCH] docs: complete documentation section in philosophy.md Filled in the TODO section for Documentation principles with guidelines for: - Comprehensive yet concise documentation - Clear examples for common use cases - API references with type info and accessibility notes - Migration guides for breaking changes - Interactive playgrounds for exploration - Transparent documentation of limitations These principles align with the existing philosophy around developer experience and accessibility. --- philosophy.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/philosophy.md b/philosophy.md index f1275b8fec..7d6b6fd677 100644 --- a/philosophy.md +++ b/philosophy.md @@ -82,7 +82,15 @@ Our goal is to create a well-funded open-source component library that the commu ### Documentation -TODO +- Documentation should be comprehensive yet concise, explaining the "why" behind design decisions +- Every component should have clear examples demonstrating common use cases +- API references should include type information, default values, and accessibility notes +- Include migration guides when introducing breaking changes +- Provide copy-pasteable code snippets that work out of the box +- Document known limitations and edge cases transparently +- Keep examples focused on one concept at a time to reduce cognitive load +- Include interactive playgrounds where possible for hands-on exploration +- Accessibility documentation should explain both what the component does automatically and what the developer is responsible for ### Misc