9.8. 样式#
9.8.1. CSS Variables#
All colors used by sphinx-design are defined as CSS variables.
Therefore they can be overriden by adding a .css
file in a _static
folder in your projects source folder (see the sphinx documentation):
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:
: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
}
9.8.2. 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-
.
Some CSS styled text
Syntax
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
(requiresdisplay: inline-block
ordisplay: 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
):
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.
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}
sd-border-0
sd-border-1
sd-border-2
sd-border-3
sd-border-4
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
sd-rounded-0
sd-rounded-1
sd-rounded-2
sd-rounded-3
sd-rounded-pill
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
sd-shadow-none
sd-shadow-sm
sd-shadow-md
sd-shadow-lg
Avatars#
Avatars can represent a user or a brand,with a logo or branded graphic (see Material Design 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
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 and material.io for good guides to animation.