{ "$schema": "aihio-design-system", "version": "2.3.0", "intents": { "action": "Any user-triggerable action.", "primary-action": "The dominant action in a given context (e.g. submit, confirm).", "secondary-action": "A supporting action (e.g. cancel, reset).", "destructive-action": "An action with irreversible or data-losing consequences.", "toggle-state": "Toggles a binary state without navigating or submitting.", "navigation": "Moves the user to a different view, section, or URL.", "selection": "Lets the user pick one item from a set.", "form-field": "Collects a single value from the user as part of a form.", "text-entry": "A form field specifically for free-form text.", "status": "Displays current state (badges, pills, counts).", "informational": "Non-blocking guidance or context.", "alert": "Important message that requires attention.", "error": "Communicates a failure or invalid state.", "container": "Groups related content without imposing meaning.", "surface": "A raised or bordered region that frames content (card, panel).", "layout": "Arranges other components spatially (tab list, grid).", "header": "A titled heading region inside a surface.", "footer": "An actions or summary region inside a surface.", "overlay": "Content that renders on top of the page (dialog, popover).", "modal": "An overlay that blocks interaction with the rest of the page.", "menu": "A list of actions triggered from an anchor element.", "identity": "Represents a person or entity (avatar, name chip).", "labeling": "Short label or tag attached to other content.", "metadata": "Ancillary descriptive text (titles, descriptions, captions).", "tabs": "Switches between sibling panels using a row of triggers.", "tabular-data": "Records laid out in rows and columns, compared by scanning down a column (a data table).", "dismissible": "Can be closed or hidden by the user." }, "components": [ { "$component": "aihio-alert", "version": "1.1.0", "description": "A callout for a message the user should notice where it is shown: a failed save, a confirmation that something worked, a warning about a setting. Only the destructive variant interrupts a screen reader.", "intents": [ "alert", "informational", "status" ], "attributes": { "variant": { "type": "enum", "values": [ "default", "success", "warning", "destructive" ], "default": "default", "description": "Visual and live-region emphasis. destructive announces assertively; success, warning, and default announce politely." } }, "slots": { "default": { "description": "Alert content" }, "title": { "description": "Alert title (use slot=\"title\")" }, "description": { "description": "Alert description (use slot=\"description\")" } }, "composition": { "allowedSlots": [ "default", "title", "description" ], "forbiddenChildren": [ "aihio-button", "aihio-toggle", "aihio-switch", "aihio-input", "aihio-combobox", "aihio-dropdown", "aihio-dialog" ] }, "a11yContract": { "handled": [ "role=\"alert\" (assertive) is set for variant=\"destructive\"; other variants get role=\"status\" (polite) so a confirmation does not interrupt the screen reader", "An author-provided role is always left alone" ], "required": [ { "when": "variant=\"destructive\"", "requirement": "Include slot=\"title\" or slot=\"description\" so assistive tech has content to announce. Colour alone is not a sufficient signal.", "severity": "warn", "rule": "alert-announced-content" }, { "when": "role is set on the alert to anything but its variant's own (alert for destructive, status otherwise)", "requirement": "Remove the role and let the variant set it: role=\"alert\" for destructive, which interrupts the screen reader, and role=\"status\" for the rest, which waits its turn.", "severity": "error", "rule": "alert-role" } ] }, "counterExamples": [ { "markup": "Oops", "reason": "variant=\"error\" is not valid. Use variant=\"destructive\" for error states.", "fix": "\n
Could not save
\n", "rule": "invalid-enum-attribute" }, { "markup": "OK", "reason": "Alerts are non-interactive surfaces. For acknowledgeable prompts use aihio-dialog.", "fix": "\n
Your changes were saved
\n", "rule": "forbidden-descendant" }, { "markup": "Saved", "reason": "role=\"alert\" interrupts the screen reader. A confirmation should announce politely — drop the role and let the success variant set role=\"status\".", "fix": "Saved", "rule": "alert-role" } ], "examples": [ { "title": "Default", "description": "Neutral information, announced politely as role=\"status\".", "markup": "\n
Heads up!
\n
You can add components to your app.
\n" }, { "title": "Destructive", "description": "A failure: the one variant announced assertively, as role=\"alert\".", "markup": "\n
Error
\n
Something went wrong.
\n" }, { "title": "Success", "description": "A confirmation that something worked.", "markup": "\n
Changes saved
\n
Your profile is up to date.
\n" }, { "title": "Warning", "description": "Something that needs attention but has not failed.", "markup": "\n
Trial ends in 3 days
\n
Add a payment method to keep your workspace active.
\n" } ] }, { "$component": "aihio-avatar", "version": "1.0.0", "description": "A round picture of a person or entity, such as the account owner in a header, falling back to initials when there is no image or it fails to load.", "intents": [ "identity", "labeling" ], "attributes": { "src": { "type": "string", "description": "Image URL for the avatar" }, "alt": { "type": "string", "description": "Alt text for the image. Initials are derived from this if no fallback is set." }, "fallback": { "type": "string", "description": "Fallback text displayed when image is unavailable" }, "size": { "type": "enum", "values": [ "sm", "md", "lg" ], "default": "md", "description": "Avatar size" } }, "composition": { "allowedChildren": [] }, "a11yContract": { "handled": [ "Image alt is forwarded from the alt attribute", "Falls back to initials derived from alt when the image fails to load" ], "required": [ { "when": "src is set", "requirement": "Provide alt describing the person or entity (e.g. alt=\"Jane Doe\"). Empty alt is only acceptable for purely decorative avatars.", "severity": "error", "rule": "avatar-alt" }, { "when": "src is not set and fallback is empty", "requirement": "Provide alt so initials can be derived, or set fallback explicitly.", "severity": "error", "rule": "avatar-fallback" } ] }, "counterExamples": [ { "markup": "", "reason": "Missing alt. Screen readers will announce only the filename.", "fix": "", "rule": "avatar-alt" }, { "markup": "JD", "reason": "Avatar renders its own content; passed children are replaced. Use the fallback attribute instead.", "fix": "", "rule": "invalid-child" } ], "examples": [ { "title": "With an image", "description": "alt names the person for screen readers.", "markup": "" }, { "title": "Initials from the name", "description": "With no src, the initials are taken from alt.", "markup": "" }, { "title": "Explicit initials, large", "description": "fallback sets the initials directly.", "markup": "" } ] }, { "$component": "aihio-badge", "version": "1.1.0", "description": "A small non-interactive label for a status, count, or category, such as Live, Beta, or 3 new.", "intents": [ "status", "labeling", "metadata" ], "attributes": { "variant": { "type": "enum", "values": [ "default", "secondary", "outline", "success", "warning", "destructive" ], "default": "default", "description": "Visual style variant" } }, "slots": { "default": { "description": "Badge text content" } }, "composition": { "allowedChildren": [ "#text" ], "forbiddenChildren": [ "aihio-button", "aihio-input", "aihio-dialog" ] }, "a11yContract": { "handled": [ "Badge stays semantically neutral: it does not add button, alert, status, or live-region roles automatically." ], "required": [ { "when": "badge conveys information not present elsewhere (e.g. unread count)", "requirement": "Include the meaning in visible text or an aria-label on the surrounding context. Badges have no inherent role.", "severity": "warn" } ] }, "counterExamples": [ { "markup": "Delete", "reason": "Badges are non-interactive labels. Put interactive elements outside the badge.", "fix": "\n Draft\n Delete\n", "rule": "forbidden-descendant" }, { "markup": "New", "reason": "variant=\"primary\" is not valid. Use variant=\"default\" for the primary style.", "fix": "New", "rule": "invalid-enum-attribute" } ], "examples": [ { "title": "Default", "markup": "New" }, { "title": "Secondary", "markup": "Draft" }, { "title": "Outline", "markup": "v2.0" }, { "title": "Destructive", "markup": "Error" } ] }, { "$component": "aihio-button", "version": "1.5.0", "description": "An action the user takes: submit a form, open a dialog, run a command. Renders a real