From b10bf078f4fe8564cbbaf9147cb4dc938b81271a Mon Sep 17 00:00:00 2001 From: James Stuckey Weber Date: Wed, 2 Jul 2025 10:42:04 -0400 Subject: [PATCH 1/6] Add initial draft of API docs --- docs/component-api.md | 289 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 docs/component-api.md diff --git a/docs/component-api.md b/docs/component-api.md new file mode 100644 index 0000000..178af27 --- /dev/null +++ b/docs/component-api.md @@ -0,0 +1,289 @@ +# Open UI Global Design System Component API Guidelines + +This document outlines the APIU guidelines for the components that are part of +the Open UI Global Design System (OUI). Additional guidelines will be needed for +the tooling and apps that support the components, as well as for any +framework-specific implementations of OUI. + +## Principles for API guidelines + +- This is a living document and meant to reflect reality. When a question arises + that is not covered, the guidelines should be updated with the new guidance. +- Code guidelines should make it *easier* to contribute, by reducing the number + of arbitrary decisions a developer needs to make, while not being onerous to + follow. This document tries to find that balance. +- When possible, these guidelines should be enforced through tooling. Otherwise, + they are enforced through the PR approval process. + +In addition to the criteria for inclusion outlined elsewhere, OUI follows these +coding principles and conventions. + +## OUI principles + +The primary implementation of the global design system are built as web +components. There will also be secondary implementations of the components. + +There will be copyable HTML/CSS/JS snippets that represent a component's output +with predefined attributes, for instance a "Success Badge" or "Primary Button". + +There will also be framework-specific implementations that either wrap or +emulate a component, with adjustments needed to make the component usable in +React, Svelte, Vue, etc. These implementations are expected to have an API and +output that aligns with the primary implementations. + +The OUI components follow these guidelines: + +- **Agnostic** - OUI components are free of any framework, CMS, or + implementation-specific conventions. These are standalone presentational UI + components that aim to share an interface across frameworks. Any framework, + CMS, or implementation-specific requirements should be minimized and scoped to + that implementation. + - For example, a Svelte implementation will have `onclick`, React will have + `onClick`, and Vue will have `@click`, but they all include `click`. This + would also be true for a custom event name and for attribute names. +- **Predictable APIs** - OUI provides consistent, clear component APIs in order to + provide a smooth user developer experience. +- **Composition over inheritance** - OUI adheres to the composition over + inheritance principle in order to create clean, extensible components that + aren't tied to specific contexts or content. + +## API guidelines + +### Component API naming conventions + +OUI provides attributes that serve as the API for user developers to interface +with OUI components. For example: + +```html + +``` + +In the above example, `text`, `iconName`, and `iconPosition` are attributes that +can accept certain values in order to render the desired UI element. + +Authoring a consistent API language provides many benefits: + +- **More efficient development** - Because the API language is consistent across + components, user developers can spend more time coding rather than reading API + documentation. Library contributors don't have to think as much about + component API naming either. +- **Shared vocuabulary between designers and developers** - When the code + library and design library use the same language, designers and developers + can spend more time collaborating rather than futzing over what things are + named. This improves team velocity and product quality. It also positions the + team to benefit from future tooling that can bring design and code closer + together (something many startups and plugins are trying to solve right now!) +- **Future changes** - Utilizing a consistent language means that future changes + and improvements are as easy as find-and-replace. + +The library adhreres to the following API naming conventions: + +#### Component names + +The component names are prefixed with `oui-`, followed by the component name, +e.g. `oui-badge`. + +#### Variants + +- `variant` should be used for primary *stylistic* variations of a component, + such as (e.g. `variant="primary"` or `variant="success"`). variant should be + used as the primary variable used to manipulate the component style. +- `inverted` should be used consistently for stylistic variations that "invert" + the color schemes (e.g. ) to work on a darker + background. Note: this is different than dark/light mode support, which is + handled elsewhere. +- `size` should be used for adjusting size attributes (e.g. `size="sm"` or + `size="lg"`). Default to `sm`, `lg`, `xl` with `md` being the undeclared + default. Note: use abbreviated t-shirt sizes: + - `sm` = Small + - `xs` = Extra small + - `md` = Medium + - `md2` = Another Medium Value + - `lg` = Large + - `xl` = Extra large + - `xxl` = Extra, extra large + +- `spacing` should be used for adjusting spacing between elements (e.g. + `spacing="condensed"`). +- `behavior` should be used for functional variations of a pattern, such as + . behavior should be used as the default for + introducing a functional variant to a component, and should be used for + mutually exclusive behaviors. +- `is[Behavior]` should be used in conjunction with behavior to add additional + behavioral variants to a component (e.g. ``). `is[Behavior]` should be the default + convention, but sometimes deviating from the is language is necessary (for + instance, ``). Whatever the language, + the name should be clear to the user whether they're toggling something on or + off. +- `align` should be used for aligning content, and should include `left`, + `center`, `right` if needed. +- `verticalAlign` should be used for aligning content vertically, and should + include `top`, `center`, `bottom`. + +### Text, Labels, Titles + +- Default to text for strings of text (e.g. ``). +- Default to title for headings, such as ``. +- Use description for non-heading text that accompanies a component, such as + ``. +- For form-related components, use the semantic label or legend, such as + ``. + +### Tag name + +If a component can be rendered as different html elements (e.g. `h1`, `h2`, +`h3`, etc), name the prop `tagName`. + +### Media + +- `imgSrc` for passing in an image source (e.g. ``) +- `imgAlt` for image alt text (e.g. ``) +- `iconName` for icon name (e.g. ``) +- `iconPosition` for controling the position of an icon (e.g. ``) + +### Composability + +#### Compound components + +Certain components (such as an accordion are card) are composed of multiple +smaller subcomponents. Compound components either require multiple components to +function correctly (e.g. an accordion and accordion itmem), or require multiple +components to be composible and flexible (such as a card with a card header, a +card body, and card footer subcomponents). + +An example of a compound component: + +```html + + + + + + + + +``` + +- Compound components are composed of a parent component (e.g. card) and + children component (e.g. card header and card footer). +- Compound component children names must always begin with the parent name. A + parent component `oui-table` means that all child components related to it + must begin with `oui-table` (such as `oui-table-body` and `oui-table-cell`). +- Compound components should generally follow a component and component-item + pattern (e.g. `oui-accordion` and `oui-accordion-item` or `oui-breadcrumbs` + and `oui-breadcrumbs-item`). +- Some composable compound components (like modal or card) should use a header, + body, footer convention (e.g. `oui-card` would have `oui-card-header`, + `oui-card-body`, and `oui-card-footer`) to serve as discrete sections. +- Compound component children are not usable outside their parent. + +#### Slots + +Content that is displayed to users can be passed as an attribute or in a slot. + +- A default slot should only be used for the primary content displayed by a + component. +- Use slots when rich text is supported. +- Don't support both an attribute and a slot for the same content. +- Avoid having some content in an attribute, and some content in a slot. + +## HTML + +### HTML principles and conventions + +- **Use semantic markup.** That means using the `