# 样式

## CSS Variables

All colors used by sphinx-design are defined as [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
Therefore they can be overriden by adding a `.css` file in a `_static` folder in your projects source folder (see [the sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)):

```python
html_static_path = ['_static']
html_css_files = ['custom.css']
```

For colors, there are nine semantic colors that can be defined.
For each of these colors you should define:

- `--sd-color-{name}` as the actual color
- `--sd-color-{name}-highlight` as the color used when the component is highlighted
  (e.g. if hovering over a button). By default, this is a 15% darker version of the original color.
- `--sd-color-{name}-text` as the color to use for text displayed on top of the color.
  By default, this is dark grey for light colors and white for dark colors.

The defaults are:

```css
:root {
    --sd-color-primary: #007bff;
    --sd-color-secondary: #6c757d;
    --sd-color-success: #28a745;
    --sd-color-info: #17a2b8;
    --sd-color-warning: #f0b37e;
    --sd-color-danger: #dc3545;
    --sd-color-light: #f8f9fa;
    --sd-color-muted: #6c757d;
    --sd-color-dark: #212529;
    --sd-color-primary-highlight: #0069d9;
    --sd-color-secondary-highlight: #5c636a;
    --sd-color-success-highlight: #228e3b;
    --sd-color-info-highlight: #148a9c;
    --sd-color-warning-highlight: #cc986b;
    --sd-color-danger-highlight: #bb2d3b;
    --sd-color-light-highlight: #d3d4d5;
    --sd-color-muted-highlight: #5c636a;
    --sd-color-dark-highlight: #1c1f23;
    --sd-color-primary-text: #fff;
    --sd-color-secondary-text: #fff;
    --sd-color-success-text: #fff;
    --sd-color-info-text: #fff;
    --sd-color-warning-text: #212529;
    --sd-color-danger-text: #fff;
    --sd-color-light-text: #212529;
    --sd-color-muted-text: #fff;
    --sd-color-dark-text: #fff;
    --sd-color-shadow: rgba(0, 0, 0, 0.15);
    --sd-color-card-border: rgba(0, 0, 0, 0.125);
    --sd-color-card-border-hover: hsla(231, 99%, 66%, 1);
    --sd-color-card-background: transparent;
    --sd-color-card-text: inherit;
    --sd-color-card-header: transparent;
    --sd-color-card-footer: transparent;
    --sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);
    --sd-color-tabs-label-hover: hsla(231, 99%, 66%, 1);
    --sd-color-tabs-label-inactive: hsl(0, 0%, 66%);
    --sd-color-tabs-underline-active: hsla(231, 99%, 66%, 1);
    --sd-color-tabs-underline-hover: rgba(178, 206, 245, 0.62);
    --sd-color-tabs-underline-inactive: transparent;
    --sd-color-tabs-overline: rgb(222, 222, 222);
    --sd-color-tabs-underline: rgb(222, 222, 222);
    --sd-fontsize-tabs-label: 1rem
}
```

## CSS Classes

For most roles/directive, it is preferentially recommended to use the available options to style components since, for example, this allows for better cross-output-format styling.

But for custom cases, these roles/directives also provide `class` options for adding CSS classes directly to element, or you can directly use the `div` directive.
All CSS classes that are part of sphinx-design are prefixed with `sd-`.

:::{div} sd-text-center sd-font-italic sd-text-primary
Some CSS styled text
:::

`````{dropdown} Syntax
:icon: code
:color: light

````{tab-set-code}
```{literalinclude} ./snippets/myst/div-basic.txt
:language: markdown
```
```{literalinclude} ./snippets/rst/div-basic.txt
:language: rst
```
````
`````

If you find yourself using a class(es) often, consider opening an issue to request a new role/directive or option!

The `div` directive also has the `style` option, which allows you to add inline CSS styles, although it is not recommended to use this option for most cases.

### Text

Classes are available for styling and alignment:

- Alignment:
  - `sd-text-justify`
  - `sd-text-left`
  - `sd-text-right`
  - `sd-text-center`
- Size (size decreases from 1 to 6):
  - `sd-fs-1`
  - `sd-fs-2`
  - `sd-fs-3`
  - `sd-fs-4`
  - `sd-fs-5`
  - `sd-fs-6`
- Weight:
  - `sd-font-weight-light`
  - `sd-font-weight-lighter`
  - `sd-font-weight-normal`
  - `sd-font-weight-bold`
  - `sd-font-weight-bolder`
- Style
  - `sd-font-italic`
  - `sd-text-decoration-none`
  - `sd-text-lowercase`
  - `sd-text-uppercase`
  - `sd-text-capitalize`
- Wrapping
  - `sd-text-wrap`
  - `sd-text-nowrap`
  - `sd-text-truncate` (requires `display: inline-block` or `display: block`)
- Color
  - `sd-text-{semantic color name}` (uses `--sd-color-{semantic color name}` CSS variable)
  - `sd-bg-text-{semantic color name}` (uses `--sd-color-{semantic color name}-text` CSS variable)

### Display

Define the layout of an element and its children (see [`display`](https://developer.mozilla.org/en-US/docs/Web/CSS/display)):

- `sd-d-none`
- `sd-d-inline`
- `sd-d-inline-block`
- `sd-d-block`
- `sd-d-grid`
- `sd-d-flex-row` (align items horizontally)
- `sd-d-flex-column` (align items vertically)
- `sd-d-inline-flex`

Variants are also available for screen-sizes (xs, sm, md, lg), e.g. `sd-d-sm-none`.

Items within a flex box can also be aligned along the major axis or minor axis, dependant on the flex-direction.
For example, using `sd-d-flex-column` and `sd-align-major-center` will center the items in the vertical direction.

- `sd-align-major-start`
- `sd-align-major-end`
- `sd-align-major-center`
- `sd-align-major-spaced` (spaced to fill the full axis)
- `sd-align-major-justify` (spaced to fill the full axis, with the first/last item on the edges of the axis)

- `sd-align-minor-start`
- `sd-align-minor-end`
- `sd-align-minor-center`

For more information, see [this guide to flexbox](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).

### Sizing

Size objects width/height by percentage:

- `sd-width-25`, `sd-height-25`
- `sd-width-50`, `sd-height-50`
- `sd-width-75`, `sd-height-75`
- `sd-width-100`, `sd-height-100`
- `sd-width-auto`, `sd-height-auto`

### Spacing

Padding (`p`) and margins (`m`) can be controlled with these classes for; (`t`)op, (`r`)ight, (`b`)ottom, (`l`)eft, `x` (left and right), and `y` (top and bottom).

Spacing are defined on a scale of 0 to 5, for example `sd-px-1` or `sd-mt-5`.

Note, for grids the special gutter classes `sd-g-{screen-size}-{spacing}` are used to set margins, or for only `x`/`y`; `sd-gx-{screen-size}-{spacing}`.

### Colors

Colors can be set using CSS variable, they are defined for the semantic color names: `primary`, `secondary`, `success`, `warning`, `danger`, `info`, `light`, `dark`, and `muted`, and specific colors `black` and `white`.

- `sd-bg-{name}`
- `sd-bg-text-{name}`
- `sd-text-{name}`
- `sd-outline-{name}`

Additional transparent colouring:

- `sd-bg-transparent`
- `sd-outline-transparent`
- `sd-text-transparent`

### Borders

Borders can be applied to elements of thickness 0 to 5, for all are a specific side:

- `sd-border-{thickness}`
- `sd-border-top-{thickness}`
- `sd-border-bottom-{thickness}`
- `sd-border-right-{thickness}`
- `sd-border-left-{thickness}`

````{grid} 1 2 3 3
:gutter: 1

```{grid-item-card}
:shadow: none
:class-card: sd-border-0

`sd-border-0`
```
```{grid-item-card}
:shadow: none
:class-card: sd-border-1

`sd-border-1`
```
```{grid-item-card}
:shadow: none
:class-card: sd-border-2

`sd-border-2`
```
```{grid-item-card}
:shadow: none
:class-card: sd-border-3

`sd-border-3`
```
```{grid-item-card}
:shadow: none
:class-card: sd-border-4

`sd-border-4`
```
```{grid-item-card}
:shadow: none
:class-card: sd-border-5

`sd-border-5`
```
````

Border can be rounded by different amounts using:

- `sd-rounded-0`
- `sd-rounded-1`
- `sd-rounded-2`
- `sd-rounded-3`
- `sd-rounded-pill`
- `sd-rounded-circle`

````{grid} 1 2 3 3
:gutter: 1

```{grid-item-card}
:shadow: none
:class-card: sd-rounded-0

`sd-rounded-0`
```
```{grid-item-card}
:shadow: none
:class-card: sd-rounded-1

`sd-rounded-1`
```
```{grid-item-card}
:shadow: none
:class-card: sd-rounded-2

`sd-rounded-2`
```
```{grid-item-card}
:shadow: none
:class-card: sd-rounded-3

`sd-rounded-3`
```
```{grid-item-card}
:shadow: none
:class-card: sd-rounded-pill

`sd-rounded-pill`
```
```{grid-item-card}
:shadow: none
:class-card: sd-rounded-circle

`sd-rounded-circle`
```
````

### Shadows

Shadows can be applied to box elements (the color of the shadow is defined using `--sd-color-shadow` CSS variable):

- `sd-shadow-none`
- `sd-shadow-sm`
- `sd-shadow-md`
- `sd-shadow-lg`

````{grid} 1 2 3 4
:gutter: 3

```{grid-item-card}
:shadow: none

`sd-shadow-none`
```
```{grid-item-card}
:shadow: sm

`sd-shadow-sm`
```
```{grid-item-card}
:shadow: md

`sd-shadow-md`
```
```{grid-item-card}
:shadow: lg

`sd-shadow-lg`
```
````

### Avatars

Avatars can represent a user or a brand,with a logo or branded graphic ([see Material Design imagery](https://material.io/design/communication/imagery.html#informational-imagery)).

These classes center an image, set their size and add a circular crop:

- `sd-avatar-xs`
- `sd-avatar-sm`
- `sd-avatar-md`
- `sd-avatar-lg`
- `sd-avatar-xl`
- `sd-avatar-inherit`
- `sd-avatar-initial`

````{grid} 1 2 3 3
:gutter: 1

```{grid-item-card} sd-avatar-xs
<img src="snippets/notebook-logo.svg" class="sd-avatar-xs sd-border-1">
```
```{grid-item-card} sd-avatar-sm
<img src="snippets/notebook-logo.svg" class="sd-avatar-sm sd-border-1">
```
```{grid-item-card} sd-avatar-md
<img src="snippets/notebook-logo.svg" class="sd-avatar-md sd-border-1">
```
```{grid-item-card} sd-avatar-lg
<img src="snippets/notebook-logo.svg" class="sd-avatar-lg sd-border-1">
```
```{grid-item-card} sd-avatar-xl
<img src="snippets/notebook-logo.svg" class="sd-avatar-xl sd-border-1">
```
````

### Load Animations

Add CSS animations when loading elements using the `sd-animate-{name}` classes:

- `sd-animate-slide-from-left`
- `sd-animate-slide-from-right`
- `sd-animate-grow100`
- `sd-animate-grow50`
- `sd-animate-grow50-rot20`

See [uxdesign.cc](https://uxdesign.cc/the-ultimate-guide-to-proper-use-of-animation-in-ux-10bd98614fa9) and [material.io](https://material.io/design/motion/understanding-motion.html#user-education) for good guides to animation.