@beehexa/design-rules 0.0.0-stage → 2611.3.3

package/dist/docs/src/brand/structure-proposal.md

@@ -0,0 +1,227 @@
+Beehexa Design System
+Website Structure Proposal
+
+Beehexa should build its design system website on the site structure of the Atlassian Design System, and borrow three parts from Material Design 3.
+1. Purpose and Scope
+Purpose: choose the structure (sections, URL paths, scope of each section) of the Beehexa design system website.
+Scope: site structure only. This document does not decide which system Beehexa takes design token values from (color, radius, spacing…). That question is still open.
+Method: public pages of Material Design 3 and the Atlassian Design System were read on October 16, 2026. Material was read in a browser; Atlassian with WebFetch and Atlassian's llms.txt. Quotes are verbatim from the linked pages.
+Status: proposal, not yet a decision.
+2. Proposed Site Structure
+Section
+Pages
+Taken from
+Get started
+Design, Develop, Content
+Atlassian (split by role)
+Foundations - Design tokens
+Tokens overview, full token list
+Atlassian
+Foundations - Guidelines
+Accessibility, Content
+Both
+Foundations - Styles
+Color, Typography, Spacing, Grid, Radius, Border, Elevation, Motion, Iconography
+Atlassian
+Foundations - Styles
+Breakpoints
+Material
+Foundations - Styles
+Interaction states
+Material
+Components
+One page per component, tabs: Examples, Code, Usage, Accessibility, Changelog
+Atlassian tabs + Material Accessibility tab
+Tools
+Stylelint and ESLint rules, Ant Design Vue theme, docs for AI agents
+Atlassian
+Release phases
+Early Access, Beta, General Availability, Deprecated
+Atlassian
+News
+Updates and changelog
+Both
+
+
+URL pattern: /section/topic/subtopic, and /components/name/tab for component pages, following Atlassian.
+
+Not included: Rovo UI and AMP Patterns (Atlassian's AI products), Devices and the per-platform Develop section (Material), illustrations and logos (covered by the Beehexa brand guide).
+3. Why This Structure
+3.1 Why Atlassian as the Base
+Web-only, B2B, data-heavy: Beehexa's product is closer to Atlassian's products. Material serves many platforms (Android, Flutter, watches, XR).
+Small team, design tokens first: Atlassian puts everything foundational in one Foundations section that starts with Tokens, with fewer top-level sections to maintain.
+Goal is to prevent drift: the Tools section with ESLint and Stylelint plugins matches the first-round guardrails.
+Code is often written by AI agents: Atlassian publishes llms.txt and guides for AI tooling.
+Frequent releases, about two per week: Changelog tabs and Release phases tell the team what changed and what is still in trial.
+Developers are the main readers: Examples and Code tabs serve them directly.
+Even URL pattern: new pages are easy to name and find.
+3.2 What to Borrow from Material
+Accessibility tab on component pages: Beehexa commits to WCAG 2.2 AA; Atlassian has no such tab.
+Dedicated Interaction states page: disabled, hover and focus are design token groups Beehexa is missing.
+Dedicated Breakpoints page: breakpoints are missing in both the brand guide and the code.
+4. Reference Comparison
+4.1 Material Design 3 Sections
+Section
+Path
+Definition (verbatim)
+Get started
+/get-started
+"Get to know Material 3 – from UX guidance and tools to reusable components and open-source code"
+Develop
+/develop
+"Implement Material Design with code and developer documentation for Jetpack Compose, Android Views, Flutter, and the web"
+Foundations
+/foundations
+"Foundations inform the basis of any great user interface, from accessibility standards to essential patterns for layout and interaction."
+Styles
+/styles
+"Styles are the visual aspects of a UI that give it a distinct look and feel. They can be customized by changing your Material theme."
+Components
+/components
+"Components are interactive building blocks for creating a user interface."
+Blog
+/blog
+"Read the latest and greatest about Material Design"
+
+
+Foundations: Accessibility, Building for all, Content design, Customizing Material, Devices, Design tokens, Interaction (incl. States), Layout (incl. Breakpoints, Grids & spacing), Usability, Material A-Z glossary.
+Styles: Color, Elevation, Icons, Motion, Shape, Spacing, Typography.
+Components: about 35, grouped by component family. Tabs: Overview, Specs, Guidelines, Accessibility.
+4.2 Atlassian Design System Sections
+Section
+Path
+Definition (verbatim)
+Get started
+/get-started
+"Start designing and developing beautiful interfaces with Atlassian Design System foundations, components, and standards."
+Foundations
+/foundations
+"Foundations create engaging user experiences. These include our tokens, guidelines, and visual styles: color, spacing, typography, and more."
+Components
+/components
+"Components are reusable building blocks that meet specific interaction needs."
+Rovo UI
+/rovo-ui
+"The AI voice of the Atlassian Design Language which defines how Rovo looks, moves, and behaves across Atlassian surfaces."
+Tools
+/tools
+"The essential tooling for Atlassian Design System: design resources, development tools, and AI tooling."
+AMP Patterns
+/amp
+"Atlassian's powerful collection of design patterns to enhance how humans and agents collaborate."
+Release phases
+/release-phases
+"Our components and foundations have different release phases and availability."
+Contact us
+/contact-us
+"How to get help from the Atlassian Design System team and contribute to the system."
+News
+/news
+"Keep up to date with our insightful design blog posts and leadership talks"
+
+
+Get started: split by role: Design, Develop, Content design, About.
+Foundations: 14 pages in 3 groups: Design tokens (Tokens); Guidelines (Accessibility, Content); Styles (Spacing, Grid, Color, Typography, Motion, Iconography, Illustrations, Logos, Elevation, Border, Radius).
+Components: about 90, grouped by function, plus Primitives, Libraries, Tooling and Deprecated. Tabs: Examples, Code, Usage, Changelog.
+4.3 Similarities
+Topic
+Material Design 3
+Atlassian
+Get started section
+Yes
+Yes
+Foundations section
+Yes
+Yes
+Foundations cover accessibility, content, design tokens, layout
+Yes
+Yes
+Core styles: color, type, spacing, radius, elevation, motion, icons
+Yes, under Styles
+Yes, under Foundations
+Components as a top-level section, path /components/name
+Yes
+Yes
+Component pages with 4 tabs
+Yes
+Yes
+Dedicated design tokens page
+Yes
+Yes
+No dedicated dark mode page
+Yes
+Yes
+News section
+Blog
+News
+
+
+Both share the same core: Get started → Foundations → Components, plus a news section.
+4.4 Differences
+Topic
+Material Design 3
+Atlassian
+Where visual styles live
+Separate Styles section
+Inside Foundations, grouped as Design tokens, Guidelines, Styles
+Radius and border
+Radius under Styles > Shape; no border page
+Separate Radius and Border pages
+Interaction states
+Dedicated page
+Part of the Color page
+Layout and breakpoints
+Several pages, incl. a dedicated Breakpoints page
+One Grid page with a breakpoint table
+Token list
+Token tab on each style page
+One All design tokens page
+Illustrations, logos
+Not covered
+Dedicated pages
+Developer docs
+Develop section per platform
+Code tab on each component + Tools section
+Component tabs
+Overview, Specs, Guidelines, Accessibility
+Examples, Code, Usage, Changelog
+Component grouping
+By component family
+By function, plus Primitives, Libraries, Tooling, Deprecated
+Guardrail tooling
+Not on the site
+ESLint, Stylelint plugins, Storybook addon
+Docs for AI agents
+Not found on the site
+llms.txt, MCP server, Develop with AI guide
+Lifecycle and support
+Not covered
+Release phases, Contact us
+Get started
+One general page
+Split by role
+Product-specific sections
+Devices (watches, XR)
+Rovo UI, AMP Patterns
+Glossary
+Yes
+No
+URL pattern
+Uneven across sections
+Even: /section/topic/subtopic
+
+5. Limits
+Only two systems were compared. Ant Design, the library app.hexasync.com uses, has not been compared yet.
+Choosing Atlassian's site structure does not mean taking design token values from Atlassian. These are separate decisions.
+Not verified: tabs of about 33 Material component pages (assumed the same as the 3 pages opened); Atlassian's old /patterns page (empty response).
+6. Sources
+Material Design 3
+Material Design 3 Design tokens
+Material Design 3 Interaction states
+Material Design 3 Breakpoints
+Atlassian Design System
+Atlassian Foundations
+Atlassian Tokens
+Atlassian Grid
+Atlassian Button component, Examples tab
+Atlassian llms.txt

package/dist/docs/src/components/ChildPages.astro

@@ -0,0 +1,25 @@
+---
+import type { NavGroup } from '../lib/navigation';
+import { langOf, localize } from '../lib/i18n';
+
+// Card list of a section's pages, shown on section index pages.
+interface Props {
+  groups: NavGroup[];
+  exclude: string;
+}
+
+const { groups, exclude } = Astro.props;
+const lang = langOf(Astro.url.pathname);
+---
+
+{groups.map((group) => {
+  const items = group.items.filter((item) => item.href !== exclude);
+  return items.length > 0 && (
+    <section class="child-pages">
+      {group.label && <h2>{group.label}</h2>}
+      <ul class="card-grid">
+        {items.map((item) => <li><a class="card" href={localize(item.href, lang)}>{item.title} <span aria-hidden="true">→</span></a></li>)}
+      </ul>
+    </section>
+  );
+})}

package/dist/docs/src/components/CodeExample.astro

@@ -0,0 +1,18 @@
+---
+import { Code } from 'astro:components';
+
+// Live preview of an HTML snippet with its source below.
+interface Props {
+  code: string;
+  lang?: 'html' | 'vue';
+  title?: string;
+}
+
+const { code, lang = 'html', title } = Astro.props;
+---
+
+<figure class="code-example">
+  {title && <figcaption>{title}</figcaption>}
+  {lang === 'html' && <div class="code-preview" set:html={code} />}
+  <Code code={code.trim()} lang={lang} />
+</figure>