<commit_before># SUIT components

Components are custom UI patterns. Components may be built up from
utilities and an additional layer of custom styles (that are themselves not yet
generic enough to be abstracted into a utility or smaller component).

* Files should be small and well commented.
* In general, components should be focused on structural presentation so that
  they work well with theming layers.
* Including example HTML in your CSS comments.

If a component file is starting to get quite large, it probably consists of
multiple, indepedent components and should be broken up into multiple files.

To use a component's styles, apply the classes directly to HTML elements. If
you have a UI pattern that is used in many places, consider creating a template
for it rather than rewriting it multiple times in different templates.

## Naming conventions

Components use _structured class names_ and _meaningful hyphens_. This is their
format:

```
[<ns>-]<ComponentName>[--modifierName|-childName]
```

This has several benefits when writing CSS and reading HTML:

* It helps to distinguish classes for base components, modifiers of components,
  and child elements.
* It keeps the specificity of selectors low.
* It helps to decouple presentation semantics from document semantics.

### namespace

If necessary, a component can be prefixed with a namespace. For example, if you
wanted to build a low-level component toolkit to be shared across projects, you
may want to distinguish it from the local app's components by using a custom
namespace.

```css
.twt-Button { /* … */ }
.twt-Tabs { /* … */ }
```

This makes it clear, when reading the HTML, which components are part of your
common library.

### ComponentName

The component's name must be written in Pascal case. Nothing else in the
HTML/CSS uses Pascal case.

```css
.MyComponent { /* … */ }
```

```html
<article class="MyComponent">
    …
</article>
```

### ComponentName--modifierName

A component modifier is a class that modifies or extends the presentation of
the base component in some form. Modifier names must be written in Camel
case. The class should be included _in addition_ to the base component class.

```css
/* Core button */
.Button { /* … */ }
/* Primary button */
.Button--primary { /* … */ }
```

```html
<button class="Button Button--primary">…</button>
```

### ComponentName-childName

A component child is a class that is attached to a child node of a component.
It's responsible for applying presentation directly to the child. Child names
must be written in Camel case.

```html
<article class="Tweet">
    <header class="Tweet-header">
        …
    </header>
    <div class="Tweet-body">
        …
    </div>
</article>
```

### is-stateOfComponent

Use `is-stateName` for state-based modifications of components. The state name
must be Camel case. Never style these classes directly; they should always be
used as a chaining class. JS can add/remove these classes. This means that the
same state names can be used in multiple contexts, but every component must
define its own styles for the state (as they are scoped to the component).

Custom component-states that can be applied/removed with JavaScript to modify
the UI. These styles must always be scoped in CSS to another class, i.e.,

```css
.Tweet { /* … */ }
.Tweet.is-expanding { /* … */ }
```

```html
<article class="Tweet is-expanded">
    …
</article>
```

### with-ComponentName

Use the `with-ComponentName` pattern to bundle styles that need to be mixed
into an element that hosts your component. The `with-*` pattern classes should
be standalone selectors, never styled as chained to a component. Treat it like
a mixin.

For example, the `with-Dropdown` class might include styles that are required
for the child `Dropdown` component to render as expected.

```css
/* The host element of a Dropdown always needs these styles */
.with-Dropdown { position: relative; }
```

```html
<article class="Tweet with-Dropdown">
    [other content]
    <div class="Dropdown is-closed">
            …
    </div><commit_msg>Fix typo in example code<commit_after># SUIT components

Components are custom UI patterns. Components may be built up from
utilities and an additional layer of custom styles (that are themselves not yet
generic enough to be abstracted into a utility or smaller component).

* Files should be small and well commented.
* In general, components should be focused on structural presentation so that
  they work well with theming layers.
* Including example HTML in your CSS comments.

If a component file is starting to get quite large, it probably consists of
multiple, indepedent components and should be broken up into multiple files.

To use a component's styles, apply the classes directly to HTML elements. If
you have a UI pattern that is used in many places, consider creating a template
for it rather than rewriting it multiple times in different templates.

## Naming conventions

Components use _structured class names_ and _meaningful hyphens_. This is their
format:

```
[<ns>-]<ComponentName>[--modifierName|-childName]
```

This has several benefits when writing CSS and reading HTML:

* It helps to distinguish classes for base components, modifiers of components,
  and child elements.
* It keeps the specificity of selectors low.
* It helps to decouple presentation semantics from document semantics.

### namespace

If necessary, a component can be prefixed with a namespace. For example, if you
wanted to build a low-level component toolkit to be shared across projects, you
may want to distinguish it from the local app's components by using a custom
namespace.

```css
.twt-Button { /* … */ }
.twt-Tabs { /* … */ }
```

This makes it clear, when reading the HTML, which components are part of your
common library.

### ComponentName

The component's name must be written in Pascal case. Nothing else in the
HTML/CSS uses Pascal case.

```css
.MyComponent { /* … */ }
```

```html
<article class="MyComponent">
    …
</article>
```

### ComponentName--modifierName

A component modifier is a class that modifies or extends the presentation of
the base component in some form. Modifier names must be written in Camel
case. The class should be included _in addition_ to the base component class.

```css
/* Core button */
.Button { /* … */ }
/* Primary button */
.Button--primary { /* … */ }
```

```html
<button class="Button Button--primary">…</button>
```

### ComponentName-childName

A component child is a class that is attached to a child node of a component.
It's responsible for applying presentation directly to the child. Child names
must be written in Camel case.

```html
<article class="Tweet">
    <header class="Tweet-header">
        …
    </header>
    <div class="Tweet-body">
        …
    </div>
</article>
```

### is-stateOfComponent

Use `is-stateName` for state-based modifications of components. The state name
must be Camel case. Never style these classes directly; they should always be
used as a chaining class. JS can add/remove these classes. This means that the
same state names can be used in multiple contexts, but every component must
define its own styles for the state (as they are scoped to the component).

Custom component-states that can be applied/removed with JavaScript to modify
the UI. These styles must always be scoped in CSS to another class, i.e.,

```css
.Tweet { /* … */ }
.Tweet.is-expanded { /* … */ }
```

```html
<article class="Tweet is-expanded">
    …
</article>
```

### with-ComponentName

Use the `with-ComponentName` pattern to bundle styles that need to be mixed
into an element that hosts your component. The `with-*` pattern classes should
be standalone selectors, never styled as chained to a component. Treat it like
a mixin.

For example, the `with-Dropdown` class might include styles that are required
for the child `Dropdown` component to render as expected.

```css
/* The host element of a Dropdown always needs these styles */
.with-Dropdown { position: relative; }
```

```html
<article class="Tweet with-Dropdown">
    [other content]
    <div class="Dropdown is-closed">
            …
    </div>
{'fraction_non_alphanumeric': 0.08592411260709915, 'fraction_numerical': 0.0, 'mean_word_length': 3.9312009656004827, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 37, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4964446', 'n_tokens_mistral': 2201, 'n_tokens_neox': 2122, 'n_words': 1127}