diff --git a/apps/docs/src/app/_app-theme.scss b/apps/docs/src/app/_app-theme.scss deleted file mode 100644 index 0b60b84e0b..0000000000 --- a/apps/docs/src/app/_app-theme.scss +++ /dev/null @@ -1,13 +0,0 @@ -@mixin kbq-docs-app-theme() { - .docs-overlay { - background: var(--kbq-background-overlay); - } - - .docs-top-overflown { - box-shadow: 0 9px 8px -12px #6c739480; - } - - .docs-markdown__a:focus { - outline: var(--kbq-link-state-focused-outline) solid; - } -} diff --git a/apps/docs/src/app/app.component.scss b/apps/docs/src/app/app.component.scss index 5b0abf67f7..d1d8f78964 100644 --- a/apps/docs/src/app/app.component.scss +++ b/apps/docs/src/app/app.component.scss @@ -23,6 +23,8 @@ bottom: 0; left: 0; right: 0; + + background: var(--kbq-background-overlay); } @media (width <= 768px) { diff --git a/apps/docs/src/app/components/anchors/_anchors-theme.scss b/apps/docs/src/app/components/anchors/_anchors-theme.scss deleted file mode 100644 index 4b9206118b..0000000000 --- a/apps/docs/src/app/components/anchors/_anchors-theme.scss +++ /dev/null @@ -1,36 +0,0 @@ -@use '../dist/components/core/styles/theming'; -@use '../dist/components/core/styles/typography'; -@use '../dist/components/core/styles/common'; - -@mixin kbq-docs-anchors-theme() { - $shadow: var(--kbq-foreground-contrast-secondary); - - .docs-anchors { - background-color: var(--kbq-background-bg); - } - - .docs-anchors__link { - outline: none; - text-decoration: none; - color: inherit; - display: -webkit-box; - -webkit-line-clamp: 2; - -webkit-box-orient: vertical; - overflow: hidden; - } - - .docs-anchors__element { - &:first-child { - padding: 0 0 0 var(--kbq-size-l); - margin: 0; - - & .docs-anchors__link { - padding: var(--kbq-size-xs) var(--kbq-size-l) var(--kbq-size-xs) 0; - } - } - - &.docs-anchors__element_active { - box-shadow: inset 3px 0 0 $shadow; - } - } -} diff --git a/apps/docs/src/app/components/anchors/anchors.component.scss b/apps/docs/src/app/components/anchors/anchors.component.scss index dbb0e7e59c..f8f60941b9 100644 --- a/apps/docs/src/app/components/anchors/anchors.component.scss +++ b/apps/docs/src/app/components/anchors/anchors.component.scss @@ -30,3 +30,33 @@ .docs-anchors__element_2 { padding-left: 48px; } + +.docs-anchors { + background-color: var(--kbq-background-bg); +} + +.docs-anchors__link { + outline: none; + text-decoration: none; + color: inherit; + display: -webkit-box; + line-clamp: 2; + -webkit-line-clamp: 2; + -webkit-box-orient: vertical; + overflow: hidden; +} + +.docs-anchors__element { + &:first-child { + padding: 0 0 0 var(--kbq-size-l); + margin: 0; + + & .docs-anchors__link { + padding: var(--kbq-size-xs) var(--kbq-size-l) var(--kbq-size-xs) 0; + } + } + + &.docs-anchors__element_active { + box-shadow: inset 3px 0 0 var(--kbq-foreground-contrast-secondary); + } +} diff --git a/apps/docs/src/app/components/component-viewer/_component-viewer-theme.scss b/apps/docs/src/app/components/component-viewer/_component-viewer-theme.scss deleted file mode 100644 index 7b513d37e5..0000000000 --- a/apps/docs/src/app/components/component-viewer/_component-viewer-theme.scss +++ /dev/null @@ -1,124 +0,0 @@ -@use '../dist/components/core/styles/theming'; -@use '../dist/components/core/styles/common/tokens'; - -@mixin kbq-docs-component-viewer-theme() { - .docs-component-header { - background: var(--kbq-background-bg); - } - - .docs-api__section { - border-color: var(--kbq-background-contrast-fade); - } - - .docs-api__section_directive .docs-api_method-name { - color: var(--kbq-line-warning) !important; - } - - .docs-api__input-marker { - color: var(--kbq-line-success) !important; - } - - .docs-api__output-marker { - color: var(--kbq-foreground-theme) !important; - } - - .kbq-docs-table { - & .kbq-markdown__code { - background: transparent !important; - } - - &.kbq-table > tbody > tr:hover { - background: none; - } - } -} - -@mixin kbq-docs-component-viewer-typography() { - // header - .docs-component-name { - font-family: Inter; - font-size: 36px; - line-height: 44px; - letter-spacing: normal; - font-weight: 700; - text-transform: none; - font-feature-settings: - 'ss01' on, - 'ss04' on; - } - - .docs-api__class-name { - font-family: JetBrains Mono; - font-size: 20px; - line-height: 28px; - letter-spacing: normal; - font-weight: 700; - text-transform: none; - font-feature-settings: initial; - } - - .docs-icons-viewer, - .docs-component-overview { - // first level - & .docs-header-link.kbq-markdown__h3 { - font-family: Inter; - font-size: 24px; - line-height: 32px; - letter-spacing: normal; - font-weight: 700; - text-transform: none; - font-feature-settings: - 'ss01' on, - 'ss04' on; - } - - // second level - & .docs-icons-viewer__table-row-header, - & .docs-api__section_method .docs-api_method-name, - & .docs-header-link.kbq-markdown__h4 { - font-family: Inter; - font-size: 20px; - line-height: 28px; - letter-spacing: normal; - font-weight: 600; - text-transform: none; - font-feature-settings: - 'ss01' on, - 'ss04' on; - } - - // third level - & .docs-header-link.kbq-markdown__h5 { - font-family: Inter; - font-size: 17px; - line-height: 20px; - letter-spacing: normal; - font-weight: 600; - text-transform: none; - font-feature-settings: - 'ss01' on, - 'ss04' on; - } - } - - .docs-component-navbar .kbq-tab-link { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } - - .docs-api__class-selector-name, - .docs-api__input-marker, - .docs-api__output-marker, - .docs-api_property-name { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big); - } - - .docs-api_method-name { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big-strong); - } - - .docs-api { - .kbq-markdown__code { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big); - } - } -} diff --git a/apps/docs/src/app/components/component-viewer/component-viewer.scss b/apps/docs/src/app/components/component-viewer/component-viewer.scss index 4ff17bf7e9..42549dd77a 100644 --- a/apps/docs/src/app/components/component-viewer/component-viewer.scss +++ b/apps/docs/src/app/components/component-viewer/component-viewer.scss @@ -1,3 +1,5 @@ +@use '../dist/components/core/styles/common/tokens'; + .kbq-docs-pre { position: relative; } @@ -251,3 +253,113 @@ } } } + +.docs-component-header { + background: var(--kbq-background-bg); +} + +.docs-api__section { + border-color: var(--kbq-background-contrast-fade); +} + +.docs-api__section_directive .docs-api_method-name { + color: var(--kbq-line-warning) !important; +} + +.docs-api__input-marker { + color: var(--kbq-line-success) !important; +} + +.docs-api__output-marker { + color: var(--kbq-foreground-theme) !important; +} + +.kbq-docs-table { + & .kbq-markdown__code { + background: transparent !important; + } + + &.kbq-table > tbody > tr:hover { + background: none; + } +} + +// header +.docs-component-name { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, display-compact-strong); +} + +.docs-api__class-name { + font-family: var(--kbq-font-family-mono); + font-size: 20px; + line-height: 28px; + letter-spacing: normal; + font-weight: 700; + text-transform: none; + font-feature-settings: initial; +} + +.docs-component-overview { + // first level + & .docs-header-link.kbq-markdown__h3 { + font-family: var(--kbq-font-family-base); + font-size: 24px; + line-height: 32px; + letter-spacing: normal; + font-weight: 700; + text-transform: none; + font-feature-settings: + 'ss01' on, + 'ss04' on; + } + + // second level + & .docs-api__section_method .docs-api_method-name, + & .docs-header-link.kbq-markdown__h4 { + font-family: var(--kbq-font-family-base); + font-size: 20px; + line-height: 28px; + letter-spacing: normal; + font-weight: 600; + text-transform: none; + font-feature-settings: + 'ss01' on, + 'ss04' on; + } + + // third level + & .docs-header-link.kbq-markdown__h5 { + font-family: var(--kbq-font-family-base); + font-size: 17px; + line-height: 20px; + letter-spacing: normal; + font-weight: 600; + text-transform: none; + font-feature-settings: + 'ss01' on, + 'ss04' on; + } +} + +// `.kbq-tab-nav-bar` is in the selector for weight: the library sets `.kbq-tab-link` typography from +// `koobiq-typography()`, which is emitted inside `.docs`, so two class names here would only tie with it. +.docs-component-navbar .kbq-tab-nav-bar .kbq-tab-link { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); +} + +.docs-api__class-selector-name, +.docs-api__input-marker, +.docs-api__output-marker, +.docs-api_property-name { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big); +} + +.docs-api_method-name { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big-strong); +} + +.docs-api { + .kbq-markdown__code { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, mono-big); + } +} diff --git a/apps/docs/src/app/components/footer/_footer-theme.scss b/apps/docs/src/app/components/footer/_footer-theme.scss deleted file mode 100644 index 9ecbaf381c..0000000000 --- a/apps/docs/src/app/components/footer/_footer-theme.scss +++ /dev/null @@ -1,28 +0,0 @@ -@use '../dist/components/core/styles/common/tokens'; - -@mixin kbq-docs-footer-theme() { - .docs-footer__label, - .kbq-dropdown__group-header .kbq-caps-compact-strong { - color: var(--kbq-foreground-contrast-secondary); - } -} - -@mixin kbq-docs-footer-typography() { - .docs-footer__label { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal); - } - - .docs-footer__control { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } - - .docs-dropdown { - .kbq-dropdown-item__text { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } - - .kbq-dropdown-item__caption { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal); - } - } -} diff --git a/apps/docs/src/app/components/footer/footer.component.html b/apps/docs/src/app/components/footer/footer.component.html index 120b847f03..c21e303533 100644 --- a/apps/docs/src/app/components/footer/footer.component.html +++ b/apps/docs/src/app/components/footer/footer.component.html @@ -5,7 +5,7 @@
@@ -65,7 +65,7 @@ #versionDropdownDropdownTrigger="kbqDropdownTrigger" #versionPicker="docsVersionPicker" docsVersionPicker - class="docs-footer__control" + class="docs-footer__control kbq-text-big" [class.kbq-active]="versionDropdownDropdownTrigger.opened" [kbqDropdownTriggerFor]="versionDropdown" > diff --git a/apps/docs/src/app/components/footer/footer.component.scss b/apps/docs/src/app/components/footer/footer.component.scss index c96cd4c86e..bcb4305966 100644 --- a/apps/docs/src/app/components/footer/footer.component.scss +++ b/apps/docs/src/app/components/footer/footer.component.scss @@ -1,3 +1,5 @@ +@use '../dist/components/core/styles/common/tokens'; + .docs-footer { box-sizing: border-box; display: flex; @@ -30,3 +32,20 @@ } } } + +.docs-footer__label, +.kbq-dropdown__group-header .kbq-caps-compact-strong { + color: var(--kbq-foreground-contrast-secondary); +} + +.docs-dropdown { + .kbq-dropdown-item__text { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); + } + + // `.kbq-dropdown-item` is in the selector for weight: the library sets the caption's typography as + // `.kbq-dropdown-item .kbq-dropdown-item__caption`, so two class names here would only tie with it. + .kbq-dropdown-item .kbq-dropdown-item__caption { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal); + } +} diff --git a/apps/docs/src/app/components/icons-viewer/_icons-viewer-theme.scss b/apps/docs/src/app/components/icons-viewer/_icons-viewer-theme.scss deleted file mode 100644 index 478574f541..0000000000 --- a/apps/docs/src/app/components/icons-viewer/_icons-viewer-theme.scss +++ /dev/null @@ -1,57 +0,0 @@ -@use '../dist/components/core/styles/theming'; -@use '../dist/components/core/styles/common/tokens'; - -@mixin kbq-docs-icons-viewer-theme() { - .docs-icons-viewer__header { - background: var(--kbq-background-bg); - } - - .docs-icons-viewer__header-text { - color: var(--kbq-foreground-contrast); - } - - .docs-icons-viewer__table-cell { - background: var(--kbq-background-bg); - border-color: var(--kbq-divider-color, var(--kbq-line-contrast-less)); - - > .docs-icons-viewer__table-cell-name { - color: var(--kbq-foreground-contrast-secondary); - } - - &:focus { - outline: 2px solid var(--kbq-theme-default); - } - - &:hover { - background: var(--kbq-states-background-transparent-hover); - } - - &:active { - background: var(--kbq-states-background-transparent-active); - } - } - - .docs-icon-preview-modal__preview-area { - background: var(--kbq-background-bg-secondary); - } -} - -@mixin kbq-docs-icons-viewer-typography() { - .docs-icon-preview-modal .kbq-modal-header.kbq-modal-title { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, title); - } - - .docs-icons-viewer__header .kbq-input, - .docs-icons-viewer__table-cell-name, - .docs-icon-preview-modal__content .kbq-select, - .docs-icon-preview-modal__buttons .kbq-button, - .kbq-select-overlay .docs-icon-preview-modal__select-option, - .docs-icon-preview-modal__description .kbq-dd, - .docs-icon-preview-modal__description .kbq-badge { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } - - .docs-icons-viewer__table-empty-results { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, display-compact); - } -} diff --git a/apps/docs/src/app/components/icons-viewer/icon-preview-modal/icon-preview-modal.scss b/apps/docs/src/app/components/icons-viewer/icon-preview-modal/icon-preview-modal.scss index a9e9a605c4..3a72ef8822 100644 --- a/apps/docs/src/app/components/icons-viewer/icon-preview-modal/icon-preview-modal.scss +++ b/apps/docs/src/app/components/icons-viewer/icon-preview-modal/icon-preview-modal.scss @@ -1,3 +1,5 @@ +@use '../dist/components/core/styles/common/tokens'; + .docs-icon-preview-modal .kbq-modal-body { display: flex; flex-direction: column; @@ -13,6 +15,8 @@ text-align: center; + background: var(--kbq-background-bg-secondary); + --icon-accent-color: var(--kbq-foreground-error); } @@ -65,3 +69,16 @@ cursor: pointer; } } + +.docs-icon-preview-modal__content .kbq-select, +.docs-icon-preview-modal__buttons .kbq-button, +.kbq-select-overlay .docs-icon-preview-modal__select-option, +.docs-icon-preview-modal__description .kbq-badge { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); +} + +// `.kbq-dl` is in the selector for weight: `__description` is itself the `kbq-dl` element, and the +// library sets the term typography as `.kbq-dl .kbq-dd`, so two class names here would only tie with it. +.kbq-dl.docs-icon-preview-modal__description .kbq-dd { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); +} diff --git a/apps/docs/src/app/components/icons-viewer/icons-viewer.scss b/apps/docs/src/app/components/icons-viewer/icons-viewer.scss index 431f9074e7..049fb98bf2 100644 --- a/apps/docs/src/app/components/icons-viewer/icons-viewer.scss +++ b/apps/docs/src/app/components/icons-viewer/icons-viewer.scss @@ -1,3 +1,5 @@ +@use '../dist/components/core/styles/common/tokens'; + .docs-icons-viewer { overflow-y: auto; @@ -63,6 +65,16 @@ width: 100%; height: 44px; + + font-family: var(--kbq-font-family-base); + font-size: 20px; + line-height: 28px; + letter-spacing: normal; + font-weight: 600; + text-transform: none; + font-feature-settings: + 'ss01' on, + 'ss04' on; } .docs-icons-viewer__table-row { @@ -163,3 +175,40 @@ overflow: hidden; text-overflow: ellipsis; } + +.docs-icons-viewer__header { + background: var(--kbq-background-bg); +} + +.docs-icons-viewer__header-text { + color: var(--kbq-foreground-contrast); + + // Duplicated from `component-viewer.scss`: the icons page is its own lazy route and never loads that + // component's stylesheet. + @include tokens.kbq-typography-level-to-styles-css-variables(typography, display-compact-strong); +} + +.docs-icons-viewer__table-cell { + background: var(--kbq-background-bg); + border-color: var(--kbq-divider-color, var(--kbq-line-contrast-less)); + + > .docs-icons-viewer__table-cell-name { + color: var(--kbq-foreground-contrast-secondary); + } + + &:focus { + outline: 2px solid var(--kbq-theme-default); + } + + &:hover { + background: var(--kbq-states-background-transparent-hover); + } + + &:active { + background: var(--kbq-states-background-transparent-active); + } +} + +.docs-icons-viewer__header .kbq-input { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); +} diff --git a/apps/docs/src/app/components/live-example-viewer/_live-example-viewer-theme.scss b/apps/docs/src/app/components/live-example-viewer/_live-example-viewer-theme.scss deleted file mode 100644 index 659cbc4b24..0000000000 --- a/apps/docs/src/app/components/live-example-viewer/_live-example-viewer-theme.scss +++ /dev/null @@ -1,18 +0,0 @@ -@use '../dist/components/core/styles/common/tokens'; - -@mixin kbq-docs-live-example-viewer-theme() { - .docs-live-example__container { - border: 1px solid var(--kbq-background-contrast-fade); - } - - .docs-live-example__footer { - border-top: 1px solid var(--kbq-background-contrast-fade); - } -} - -@mixin kbq-docs-live-example-viewer-typography() { - .docs-live-example__footer, - .docs-live-example__footer .kbq-link { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } -} diff --git a/apps/docs/src/app/components/live-example-viewer/docs-live-example-viewer.html b/apps/docs/src/app/components/live-example-viewer/docs-live-example-viewer.html index b3c9da0363..abc0086bf3 100644 --- a/apps/docs/src/app/components/live-example-viewer/docs-live-example-viewer.html +++ b/apps/docs/src/app/components/live-example-viewer/docs-live-example-viewer.html @@ -11,7 +11,7 @@
} -
+
.docs-sidenav__category-text { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, subheading); + } +} + +@media (width <= 768px) { + .docs-sidenav { + background-color: var(--kbq-background-bg); + } +} + +@media (width <= 768px) { + // Level switches with the viewport, so it can't be a class on the element. + .docs-sidenav__category { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, title); + } +} diff --git a/apps/docs/src/app/components/welcome/_welcome-theme.scss b/apps/docs/src/app/components/welcome/_welcome-theme.scss deleted file mode 100644 index 5269939375..0000000000 --- a/apps/docs/src/app/components/welcome/_welcome-theme.scss +++ /dev/null @@ -1,56 +0,0 @@ -@use '../dist/components/core/styles/common/tokens'; - -@mixin kbq-docs-welcome-theme() { - .docs-footer__label { - color: var(--kbq-foreground-contrast-secondary); - } - - .docs-welcome__category-item-title { - color: var(--kbq-foreground-contrast-secondary); - } - - .docs-welcome__category-item { - border-radius: var(--kbq-size-border-radius); - - &:hover, - &:focus-visible { - .docs-welcome__category-item-title { - color: var(--kbq-states-foreground-theme-hover); - } - } - - &:focus-visible { - outline: 2px solid var(--kbq-states-foreground-theme-hover); - } - } - - .docs-welcome__category-item:focus { - border-color: var(--kbq-states-line-focus-theme); - } -} - -@mixin kbq-docs-welcome-typography() { - .docs-welcome__header { - font-family: Inter; - font-size: 36px; - line-height: 44px; - letter-spacing: normal; - font-weight: 700; - text-transform: none; - font-feature-settings: - 'ss01' on, - 'ss04' on; - } - - .docs-welcome__description { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } - - .docs-welcome__category-title { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, title); - } - - .docs-welcome__category-item-title { - @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-big); - } -} diff --git a/apps/docs/src/app/components/welcome/welcome.component.html b/apps/docs/src/app/components/welcome/welcome.component.html index 721c6cac50..085edbf7e4 100644 --- a/apps/docs/src/app/components/welcome/welcome.component.html +++ b/apps/docs/src/app/components/welcome/welcome.component.html @@ -2,13 +2,13 @@ {{ t('welcomeTitle') }} -
+
{{ t('welcomeDescription') }}
@for (category of structureCategories; track category) {
-
{{ category.name[locale()] }}
+
{{ category.name[locale()] }}
@let theme = currentTheme(); @@ -21,7 +21,7 @@ [ngSrc]="`/assets/images/welcome/${item.svgPreview || 'generic'}-${theme}.png`" [alt]="item.id" /> -
{{ item.name[locale()] }}
+
{{ item.name[locale()] }}
}
diff --git a/apps/docs/src/app/components/welcome/welcome.component.scss b/apps/docs/src/app/components/welcome/welcome.component.scss index 448caf3a06..51f7a8fb50 100644 --- a/apps/docs/src/app/components/welcome/welcome.component.scss +++ b/apps/docs/src/app/components/welcome/welcome.component.scss @@ -1,3 +1,5 @@ +@use '../dist/components/core/styles/common/tokens'; + .docs-welcome { display: flex; flex-direction: column; @@ -74,3 +76,26 @@ padding: 0 var(--kbq-size-7xl) 160px var(--kbq-size-7xl); } } + +.docs-welcome__category-item-title { + color: var(--kbq-foreground-contrast-secondary); +} + +.docs-welcome__category-item { + border-radius: var(--kbq-size-border-radius); + + &:hover, + &:focus-visible { + .docs-welcome__category-item-title { + color: var(--kbq-states-foreground-theme-hover); + } + } + + &:focus-visible { + outline: 2px solid var(--kbq-states-foreground-theme-hover); + } +} + +.docs-welcome__header { + @include tokens.kbq-typography-level-to-styles-css-variables(typography, display-compact-strong); +} diff --git a/apps/docs/src/main.scss b/apps/docs/src/main.scss index 03974a6535..fd9db3aa27 100644 --- a/apps/docs/src/main.scss +++ b/apps/docs/src/main.scss @@ -9,6 +9,7 @@ @use './styles/callout'; @use './styles/examples'; @use './styles/code-snippet'; +@use './styles/hot-keys'; // Import theme // https://github.com/koobiq/data-grid/blob/main/packages/ag-grid-angular-theme/README.md diff --git a/apps/docs/src/styles/_hot-keys.scss b/apps/docs/src/styles/_hot-keys.scss index 176cd13189..afc9373795 100644 --- a/apps/docs/src/styles/_hot-keys.scss +++ b/apps/docs/src/styles/_hot-keys.scss @@ -1,11 +1,3 @@ -@mixin docs-hot-key-button-theme() { - .docs-hot-key-button { - color: var(--kbq-foreground-contrast); - border-color: var(--kbq-line-contrast-fade); - box-shadow: var(--kbq-shadow-card); - } -} - .docs-hot-key-button { display: inline-block; min-width: 32px; @@ -19,9 +11,13 @@ padding: 7px; - font-family: Inter; + font-family: var(--kbq-font-family-base); font-size: 14px; line-height: 16px; letter-spacing: -0.14px; text-align: center; + + color: var(--kbq-foreground-contrast); + border-color: var(--kbq-line-contrast-fade); + box-shadow: var(--kbq-shadow-card); } diff --git a/apps/docs/src/styles/_markdown.scss b/apps/docs/src/styles/_markdown.scss index 272600c1a5..29af3b2155 100644 --- a/apps/docs/src/styles/_markdown.scss +++ b/apps/docs/src/styles/_markdown.scss @@ -16,3 +16,10 @@ margin-bottom: 0 !important; } } + +.docs-markdown__a:focus { + outline-style: solid; + outline-width: var(--kbq-link-size-state-focused-outline-width, 2px); + outline-color: var(--kbq-link-state-focused-outline); + outline-offset: var(--kbq-link-size-state-focused-outline-offset, 0px); +} diff --git a/apps/docs/src/styles/_theme-kbq.scss b/apps/docs/src/styles/_theme-kbq.scss index ad9fde1da6..ad269556b9 100644 --- a/apps/docs/src/styles/_theme-kbq.scss +++ b/apps/docs/src/styles/_theme-kbq.scss @@ -6,18 +6,6 @@ @use '../dist/components/core/styles/koobiq-theme' as *; -@use '../app/app-theme'; -@use '../app/components/icons-viewer/icons-viewer-theme'; -@use '../app/components/component-viewer/component-viewer-theme'; -@use '../app/components/anchors/anchors-theme'; -@use '../app/components/footer/footer-theme'; -@use '../app/components/sidenav/sidenav-theme'; -@use '../app/components/welcome/welcome-theme'; -@use '../app/components/live-example-viewer/live-example-viewer-theme'; -@use '../app/components/page-not-found/page-not-found-theme'; - -@use '../styles/hot-keys'; - @include components.kbq-core(); @include visual.body-html(); @@ -28,32 +16,10 @@ @include tokens.kbq-typography-level-to-styles-css-variables(typography, text-normal); @include koobiq-typography(); - - @include component-viewer-theme.kbq-docs-component-viewer-typography(); - @include footer-theme.kbq-docs-footer-typography(); - @include sidenav-theme.kbq-docs-sidenav-typography(); - @include icons-viewer-theme.kbq-docs-icons-viewer-typography(); - @include welcome-theme.kbq-docs-welcome-typography(); - @include live-example-viewer-theme.kbq-docs-live-example-viewer-typography(); -} - -// Include all theme styles for the components. -@mixin docs-components-theme() { - @include app-theme.kbq-docs-app-theme(); - @include component-viewer-theme.kbq-docs-component-viewer-theme(); - @include anchors-theme.kbq-docs-anchors-theme(); - @include footer-theme.kbq-docs-footer-theme(); - @include sidenav-theme.kbq-docs-sidenav-theme(); - @include icons-viewer-theme.kbq-docs-icons-viewer-theme(); - @include live-example-viewer-theme.kbq-docs-live-example-viewer-theme(); - @include hot-keys.docs-hot-key-button-theme(); - @include page-not-found-theme.kbq-docs-page-not-found-theme(); - @include welcome-theme.kbq-docs-welcome-theme(); } @mixin kbq-docs-theme() { @include koobiq-theme(); - @include docs-components-theme(); & { background: var(--kbq-background-bg); diff --git a/docs/guides/migration.ru.md b/docs/guides/migration.ru.md index fe6294451f..948f44479f 100644 --- a/docs/guides/migration.ru.md +++ b/docs/guides/migration.ru.md @@ -35,7 +35,7 @@ npm install @messageformat/core #### Новая темизация -Теперь темизация более простая и строится на основе CSS-переменных. [Темизация. Как использовать](https://koobiq.io/ru/main/theming/overview#как-использовать?). +Теперь темизация более простая и строится на основе CSS-переменных. [Темизация](https://koobiq.io/ru/main/theming/overview). Примеры: diff --git a/docs/guides/theming.en.md b/docs/guides/theming.en.md index c5414bb354..36050cf94c 100644 --- a/docs/guides/theming.en.md +++ b/docs/guides/theming.en.md @@ -1,27 +1,28 @@ -### What's new? +A theme in Koobiq is a set of CSS variables. Switching a theme swaps the values; nothing else has to change. This guide shows how to plug a theme in, how to switch it, and how to use its values in your own styles. -Using components is now simpler! We are moving toward full component isolation, making it easy to plug in and use components. +### How theming works -- You no longer need to import separate SCSS files to change component colors, sizes, and fonts. -- Almost all components define their styles using CSS variables that are already included in the component code. This makes styles more transparent and easier to understand. -- A few small components cannot load styles on their own, so those styles need to be included globally. -- We use global design-system CSS variables for colors, sizes, and fonts. This makes the code more readable and simplifies application theming — improving both code readability and the theming process significantly. +There are three layers. -### How to use +**Global variables** describe the design system: colors, sizes, fonts. They come from the `@koobiq/design-tokens` package and are declared under the theme selector — `.kbq-light` or `.kbq-dark`. These are the values you reach for in your own styles. -1. [Install the Koobiq design system package](/main/installation). -2. Include the `css-tokens.css`, `css-tokens-light.css`, and `css-tokens-dark.css` files to use the global design-system values such as colors, sizes, and font settings. -3. [Include the prebuilt styles file](#including-the-prebuilt-styles-file) in your main styles file. This step is required for components and overlays (e.g. popups) to render correctly. -4. Add the `kbq-light` selector to the `` element of your HTML document for the light theme, or `kbq-dark` for the dark theme. -5. Import a component and use it in your markup! 🚀 +**Component variables** are used inside Koobiq components. Each one is named after its component (`--kbq-button-*`, `--kbq-alert-*`) and points to a global variable. The component declares them itself, so nothing extra has to be included. -#### Including the prebuilt styles file +**Your styles** use the global variables directly. No imports, no mixins, no registration in a single theme entry point. + +Adding a theme to the page means putting a class on ``. Everything below it — components and your own markup alike — picks up the new values automatically, because all of it reads the same variables. + +### Setup + +- [Install the Koobiq package](/main/installation). +- Include `css-tokens.css`, `css-tokens-light.css` and `css-tokens-dark.css` — these hold the global values. +- Include the prebuilt styles in your main stylesheet. Components and overlays (popups, dropdowns) need this to render correctly: ```sass @use '@koobiq/components/prebuilt-themes/theme.css'; ``` -Here is what the `body` tag in `index.html` looks like after adding the required classes: +- Add the theme class to ``: ```html @@ -29,98 +30,165 @@ Here is what the `body` tag in `index.html` looks like after adding the required ``` -The `kbq-app-background` class applies the base theme styles to the application — background and text colors. +`kbq-app-background` paints the page itself — background and text color. + +- Import a component and use it. 🚀 ### Switching themes -To switch themes, simply change the corresponding selector to go from dark to light (or vice versa), for example from `kbq-dark` to `kbq-light`. -Color values will be automatically adapted to the selected theme. +Use `KbqThemeService`. It puts the right class on ``, remembers the choice, and in `'auto'` mode follows the system color scheme. -Use [ThemeService](https://github.com/koobiq/angular-components/tree/main/packages/components/core/services/theme.service.ts) to switch themes. Example: +There are three modes: `'light'`, `'dark'` and `'auto'`. **`'auto'` is the default.** The system color scheme is supported out of the box: no `matchMedia` subscription of your own. + +The service exposes its current state as signals, so you can read it straight from a template: ```ts -import { ThemeService } from '@koobiq/components/core'; -import { Component } from '@angular/core'; - -@Component() -class AppComponent { - constructor(private themeService: ThemeService) { - /* the light theme will become active, and the class `kbq-light` will be added to the `body` tag */ - this.themeService.setTheme(0); - } -} +protected readonly themeService = inject(KbqThemeService); ``` +```html + +``` + +If you have more than two themes and need a list rather than a light/dark switch, you can pin one by name. See [Core](/components/core) for the details and a live example. + #### Theme selectors -Available selectors for the dark and light themes: +| Theme | Selector | +| ----- | ---------- | +| Light | .kbq-light | +| Dark | .kbq-dark | -| Theme | Selectors | -| ----- | ------------------------------------------ | -| Dark | .kbq-dark, .theme-dark, .kbq-theme-dark | -| Light | .kbq-light, .theme-light, .kbq-theme-light | +#### Settings -We recommend using the selectors defined in `ThemeService` (`kbq-dark` for dark and `kbq-light` for light). +Pass the settings when the app starts: -#### Switching based on the OS theme +```ts +import { kbqThemeProvider } from '@koobiq/components/core'; -This can be implemented using [window.matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia). +bootstrapApplication(AppComponent, { + providers: [kbqThemeProvider({ mode: 'auto', storageKey: 'my-app-theme' })] +}); +``` -To switch the theme based on the operating system setting, three steps are required: +The choice is saved between visits — in `localStorage` by default. Apps rendered on the server can store it in a cookie instead, so the server already knows which theme to render: provide `KbqThemeCookieStore` through the `KBQ_THEME_STORE` token. -- Define a media query to detect the user's preferred theme: +### Using theme values in your own styles -```javascript -colorAutomaticTheme = window.matchMedia('(prefers-color-scheme: light)'); +Write the variable where you need the value: + +```css +.my-component-text { + color: var(--kbq-foreground-contrast-secondary); +} ``` -- Add a theme object to the themes array that is passed to `ThemeService` during application initialization. In this object, the `className` property is set conditionally: +Nothing to import, no mixin to write, nothing to register in a single theme entry point. The value resolves in the browser, so it changes on its own when the theme changes. -```javascript -{ - name: 'Match system', - className: this.colorAutomaticTheme.matches ? Themes.Default : Themes.Dark, - selected: false -}, -``` + + +The full list of global variables is on the [Design tokens](/main/design-tokens/colors) page. + +### Overriding a component's variables -- Subscribe to user theme updates and set the active theme whenever it changes: +When a component's default look doesn't fit, change the values of its variables rather than its styles. Start by knowing where those variables are declared, because that determines how you reach them. Every component sets them on its own selector, in a file next to itself: -```javascript -this.colorAutomaticTheme.addEventListener('change', this.setAutoTheme); +```css +/* button-tokens.scss */ +.kbq-button, +.kbq-button-icon { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-contrast); +} ``` -An example implementation of theme switching in the Koobiq documentation can be found [here.](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/app/components/navbar/navbar.component.ts) +The button sets the variable on itself, so a blanket declaration in `:root` simply won't be seen. For an override to work, you have to hit that same element. + +That leaves two approaches. -### Component customization +**Change a single instance.** Give it a class of your own and set the variable there. The class lands on the same element as the default value and, coming later, wins: -You can change colors, sizes, and fonts by overriding the component's CSS variables with the desired values. For example: +```html + + + +``` + +**Change every component of that type in the app.** This needs a selector that outranks the component's own. The simplest one to add is the theme selector — which also lets you give light and dark different values, when one color won't do for both: ```css -.kbq-dark .kbq-alert { - --kbq-alert-default-contrast-container-background: var(--kbq-foreground-contrast-secondary); - --kbq-alert-default-contrast-container-title: var(--kbq-background-contrast-fade); +.kbq-light .kbq-button { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error); +} + +.kbq-dark .kbq-button { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error-fade); +} +``` + +Rules like these are worth keeping in one file, loaded after the design system's styles — then all of the app's overrides live in one place instead of scattering across components. + +### Building your own component + +Your component reads the same global variables the library reads. Give it a stylesheet and turn off style encapsulation — that is the whole setup: + +```ts +@Component({ + selector: 'my-card', + templateUrl: './my-card.html', + styleUrl: './my-card.scss', + encapsulation: ViewEncapsulation.None, + changeDetection: ChangeDetectionStrategy.OnPush +}) +export class MyCard {} +``` + +```scss +.my-card { + padding: var(--kbq-size-l); + border: var(--kbq-size-border-width) solid var(--kbq-line-contrast-less); + border-radius: var(--kbq-size-border-radius); + + background: var(--kbq-background-card); + color: var(--kbq-foreground-contrast); } ``` -### Compatibility +There is **no** need to write a separate `_my-card-theme.scss` mixin and then register it in a single theme entry point. + +### Rebranding with a single file + +You can restyle the whole app by overriding CSS variables in one place: + +```css +.kbq-light { + --kbq-background-contrast: #1a3a6b; + --kbq-foreground-contrast: #0d1b2a; +} + +.kbq-dark { + --kbq-background-contrast: #7ba7e8; + --kbq-foreground-contrast: #e8eef7; +} +``` -Stable with `@koobiq/design-tokens@3.5.1`. +Load that file after the design system's own, and every component follows. -### Using CSS variables +One honest limitation: this works at the global layer. Component variables are declared on the component's selector, so a single global file can't reach them — you would need a rule per component, as shown above. -If you are already using CSS variables from the `@koobiq/design-tokens` package, you need to remove the CSS variables for all components included in the design system. -They now have default values built in, so you no longer need them. +### Where to find the variables -Files that need to be updated: +Global variables, with their values and previews: [Design tokens](/main/design-tokens/colors). -- css-tokens.css — component sizes -- css-tokens-light.css — component colors for the light theme -- css-tokens-dark.css — component colors for the dark theme -- css-tokens-font.css — font, its sizes, and parameters for the component. This file can be removed. +Component variables don't have a rendered reference page yet — a proper one is on the way. Until then, read them from the source:
- List of design system components with links to their CSS variables: + Component variables, by component
  • accordion
  • alert
    • @@ -173,26 +241,17 @@ Files that need to be updated:
-### Token value sources +### Where the values come from -**Design system tokens** are a set of values that define the visual style of our components. -They are stored in the [@koobiq/design-tokens](https://github.com/koobiq/design-tokens) package and allow us to easily manage and maintain consistent styles across all components. +**Design system tokens** are the values that define how our components look. They live in the [@koobiq/design-tokens](https://github.com/koobiq/design-tokens) package. -**Component CSS variables** are a set of values used in component styles. They are derived from design tokens and live in the `@koobiq/components` repository. -This makes it easy to use tokens in component styles and speeds up development, including design reviews. +**Component variables** are the values used inside component styles. They are derived from the design tokens and live in the `@koobiq/components` repository, next to the components themselves.
Note
-Component tokens in the `@koobiq/design-tokens` package are no longer being updated. +Component tokens in the `@koobiq/design-tokens` package are no longer updated and will be removed in version 4.0.0. If you still have them in your own copies of `css-tokens.css`, `css-tokens-light.css`, `css-tokens-dark.css` or `css-tokens-font.css`, delete them — components carry their own defaults now.
- -### Roadmap - -- We will update our component CSS variables and replace them with direct references to global design-system CSS variables where applicable. -- Component tokens will be removed from the `@koobiq/design-tokens` package in version 4.0.0. -- We will create a page displaying all global design-system tokens with their visual representations. -- Component tokens in CSS variable format will be stored in the Angular components repository `@koobiq/components`. diff --git a/docs/guides/theming.ru.md b/docs/guides/theming.ru.md index 24c7da31a1..fc9e6d8f30 100644 --- a/docs/guides/theming.ru.md +++ b/docs/guides/theming.ru.md @@ -1,27 +1,28 @@ -### Что нового? +Тема в Koobiq — это набор CSS-переменных. Смена темы меняет значения переменных, всё остальное остаётся как есть. Здесь описано, как подключить тему, как её переключать и как брать её значения в своих стилях. -Теперь использование компонентов стало проще! Мы движемся к полной изоляции компонентов, что позволит вам легко подключать и использовать их. +### Как устроена темизация -- Больше не нужно подключать отдельные файлы SCSS для изменения цветов, размеров и шрифтов компонентов. -- Практически во всех компонентах стили задаются с помощью CSS-переменных, которые уже включены в код компонента. Это делает стили более прозрачными и понятными. -- Некоторые маленькие компоненты не могут самостоятельно подключать стили, поэтому их нужно подключить глобально. -- Мы используем глобальные CSS-переменные дизайн-системы для цветов, размеров и шрифтов. Это делает код более читаемым и упрощает изменение темы приложения. Это не только улучшает читабельность кода, но и значительно упрощает процесс темизации. +Есть три уровня. -### Как использовать? +**Глобальные переменные** описывают дизайн-систему: цвета, размеры, шрифты. Они приходят из пакета `@koobiq/design-tokens` и объявлены под селектором темы — `.kbq-light` или `.kbq-dark`. Именно ими вы пользуетесь в своих стилях. -1. [Установите пакет дизайн системы Koobiq](/ru/main/installation). -2. Подключите файлы `css-tokens.css`, `css-tokens-light.css`, `css-tokens-dark.css` для использования глобальных значений дизайн-системы, например, цветов, размеров и параметров шрифтов. -3. [Подключите файл преднастроенных стилей](#подключение-файла-преднастроенных-стилей) в свой основной файл стилей. Этот шаг нужен для правильного отображения компонентов и оверлеев (например, всплывающих окон). -4. Добавьте селектор `kbq-light` к элементу `` вашего HTML-документа для использования светлой темы и `kbq-dark` для темной темы. -5. Импортируйте компонент и используйте его в вёрстке!🚀 +**Переменные компонента** нужны внутри компонентов Koobiq. Имя каждой начинается с названия компонента (`--kbq-button-*`, `--kbq-alert-*`), а значение ссылается на глобальную переменную. Компонент объявляет их сам, поэтому отдельно подключать ничего не нужно. -#### Подключение файла преднастроенных стилей +**Ваши стили** обращаются к глобальным переменным напрямую. Ни импортов, ни миксинов, ни регистрации в едином источнике темы. + +Подключить тему — значит поставить класс на ``. Всё, что внутри, и компоненты, и ваша вёрстка, подхватит новые значения само, потому что читает одни и те же переменные. + +### Подключение + +- [Установите пакет Koobiq](/ru/main/installation). +- Подключите файлы `css-tokens.css`, `css-tokens-light.css` и `css-tokens-dark.css` — в них лежат глобальные значения. +- Подключите файл готовых стилей в свой основной файл. Без него компоненты и всплывающие элементы (окна, выпадающие списки) отобразятся неправильно: ```sass @use '@koobiq/components/prebuilt-themes/theme.css'; ``` -Так выглядит тег `body` в `index.html` после добавления необходимых классов: +- Добавьте класс темы на ``: ```html @@ -29,99 +30,165 @@ ``` -Класс `kbq-app-background` используется для применения базовых стилей темы к приложению - цвет фона и текста. +Класс `kbq-app-background` красит саму страницу — фон и цвет текста. + +- Импортируйте компонент и пользуйтесь. 🚀 ### Переключение тем -Для переключения темы достаточно изменить соответствующий селектор, чтобы перейти от темной к светлой теме (или наоборот). Например, с `kbq-dark` на `kbq-light`. -Цветовые значения будут автоматически адаптированы под выбранную тему. +Для этого есть `KbqThemeService`. Он ставит нужный класс на ``, запоминает выбор и в режиме `'auto'` следует системной цветовой схеме. + +Режима три: `'light'`, `'dark'` и `'auto'`. **По умолчанию — `'auto'`.** Системная цветовая схема поддерживается из коробки: подписываться на `matchMedia` вручную не нужно. -Для переключения тем используйте [ThemeService.](https://github.com/koobiq/angular-components/tree/main/packages/components/core/services/theme.service.ts) Вот пример: +Текущее состояние сервис отдаёт сигналами, их можно читать прямо в шаблоне: ```ts -import { ThemeService } from '@koobiq/components/core'; -import { Component } from '@angular/core'; - -@Component() -class AppComponent { - constructor(private themeService: ThemeService) { - /* светлая тема станет активной, к тегу `body` добавится класс `kbq-light` */ - this.themeService.setTheme(0); - } +protected readonly themeService = inject(KbqThemeService); +``` + +```html + +``` + +Если тем больше двух и нужен список, а не переключатель «светлая/тёмная», тему можно закрепить по имени. Подробности и живой пример — на странице [Core](/ru/components/core). + +#### Селекторы тем + +| Тема | Селектор | +| ------- | ---------- | +| Светлая | .kbq-light | +| Тёмная | .kbq-dark | + +#### Настройки + +Настройки передаются при запуске приложения: + +```ts +import { kbqThemeProvider } from '@koobiq/components/core'; + +bootstrapApplication(AppComponent, { + providers: [kbqThemeProvider({ mode: 'auto', storageKey: 'my-app-theme' })] +}); +``` + +Выбор темы сохраняется между визитами — по умолчанию в `localStorage`. Приложения, которые собираются на сервере, могут хранить его в куке: тогда сервер сразу знает, какую тему рисовать. Для этого подключите `KbqThemeCookieStore` через токен `KBQ_THEME_STORE`. + +### Как брать значения темы в своих стилях + +Напишите переменную там, где нужно значение: + +```css +.my-component-text { + color: var(--kbq-foreground-contrast-secondary); } ``` -#### Селекторы для тем +Ничего не импортируется, миксин писать не нужно, регистрировать его в едином источнике темы тоже. Значение подставляется в браузере, поэтому при смене темы оно меняется само. -Вот таблица доступных селекторов для темной и светлой тем: + -| Тема | Селекторы | -| ------- | ------------------------------------------ | -| Темная | .kbq-dark, .theme-dark, .kbq-theme-dark | -| Светлая | .kbq-light, .theme-light, .kbq-theme-light | +Полный список глобальных переменных — на странице [Дизайн-токены](/ru/main/design-tokens/colors). -Мы рекомендуем использовать те селекторы, которые указаны в сервисе `ThemeService` (`kbq-dark` для темной и `kbq-light` для светлой). +### Переопределение переменных компонента -#### Переключение по выбранной в ОС теме +Если стандартный вид компонента не подходит, менять нужно не его стили, а значения его переменных. Сначала стоит понять, где эти переменные объявлены — от этого зависит, как до них дотянуться. Каждый компонент задаёт их на своём селекторе, в файле рядом с собой: -Данный механизм возможно реализовать с помощью [window.matchMedia](https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia); +```css +/* button-tokens.scss */ +.kbq-button, +.kbq-button-icon { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-contrast); +} +``` -Для реализации переключения темы в зависимости от операционной системы необходимы выполнить 3 условия: +Кнопка задаёт переменную на себе, поэтому общее объявление в `:root` она просто не увидит. Чтобы переопределение сработало, нужно попасть в тот же самый элемент. -- Определить медиа-запрос для получения пользовательской темы: +Отсюда два рабочих способа. + +**Поменять один экземпляр.** Повесьте на него свой класс и задайте переменную в нём — класс окажется на том же элементе, что и стандартное значение, и, поскольку идёт следом, победит: + +```html + -```javascript -colorAutomaticTheme = window.matchMedia('(prefers-color-scheme: light)'); + ``` -- Добавить объект темы в массив тем, который будет подключаться в `ThemeService` при инициализации приложения. В данной теме свойство `className` будет устанавливаться по условию +**Поменять все компоненты этого типа в приложении.** Здесь нужен селектор потяжелее, чем у самого компонента. Проще всего добавить перед ним селектор темы: заодно можно задать разные значения для светлой и тёмной, если один цвет на обе не годится: + +```css +.kbq-light .kbq-button { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error); +} -```javascript -{ - name: 'Как в системе', - className: this.colorAutomaticTheme.matches ? Themes.Default : Themes.Dark, - selected: false -}, +.kbq-dark .kbq-button { + --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error-fade); +} ``` -- Подписаться на обновление темы пользователя и устанавливать активную тему при обновлении. +Такие правила удобно держать в одном файле и подключать его после стилей дизайн-системы — тогда все переопределения приложения лежат в одном месте, а не расползаются по компонентам. + +### Компонент на основе темы -```javascript -this.colorAutomaticTheme.addEventListener('change', this.setAutoTheme); +Кастомный компонент читает те же глобальные переменные, что и библиотека. Дайте ему файл стилей и отключите изоляцию стилей — это вся настройка: + +```ts +@Component({ + selector: 'my-card', + templateUrl: './my-card.html', + styleUrl: './my-card.scss', + encapsulation: ViewEncapsulation.None, + changeDetection: ChangeDetectionStrategy.OnPush +}) +export class MyCard {} +``` + +```scss +.my-card { + padding: var(--kbq-size-l); + border: var(--kbq-size-border-width) solid var(--kbq-line-contrast-less); + border-radius: var(--kbq-size-border-radius); + + background: var(--kbq-background-card); + color: var(--kbq-foreground-contrast); +} ``` -Пример реализации переключения тем в документации Koobiq [тут.](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/app/components/navbar/navbar.component.ts) +Отдельный миксин `_my-card-theme.scss`, который потом нужно регистрировать в едином источнике темы, писать **не надо**. -### Кастомизация компонентов +### Смена оформления одним файлом -Изменить цвета, размеры и шрифты можно задав соответствующие значения CSS-переменным компонента. -Например: +Оформление всего приложения меняется в одном месте: ```css -.kbq-dark .kbq-alert { - --kbq-alert-default-contrast-container-background: var(--kbq-foreground-contrast-secondary); - --kbq-alert-default-contrast-container-title: var(--kbq-background-contrast-fade); +.kbq-light { + --kbq-background-contrast: #1a3a6b; + --kbq-foreground-contrast: #0d1b2a; } -``` -### Совместимость +.kbq-dark { + --kbq-background-contrast: #7ba7e8; + --kbq-foreground-contrast: #e8eef7; +} +``` -Работает стабильно с `@koobiq/design-tokens@3.5.1`. +Подключите этот файл после файлов дизайн-системы — и все компоненты подхватят новые значения. -### Использование CSS-переменных +Одна честная оговорка: так работает глобальный уровень. Переменные компонента объявлены на его селекторе, поэтому одним общим файлом до них не дотянуться — придётся писать правило на каждый компонент, как показано выше. -Если уже используются CSS-переменные из пакета `@koobiq/design-tokens`, необходимо удалить CSS-переменные для всех включенных в дизайн систему компонентов. -В них используется значение по умолчанию, они вам больше не нужны. +### Где посмотреть переменные -В каких файлы необходимо внести изменения: +Глобальные переменные, со значениями и образцами: [Дизайн-токены](/ru/main/design-tokens/colors). -- css-tokens.css - размеры компонента -- css-tokens-light.css - цвета компонента для светлой темы -- css-tokens-dark.css - цвета компонента для темной темы -- css-tokens-font.css - шрифт, его размеры и параметры для компонента. Его можно удалить. +Отдельной страницы с переменными компонентов пока нет, мы её готовим. Пока смотрите в исходниках:
- Список компонентов дизайн системы со ссылками на их CSS-переменные: + Переменные по компонентам
  • accordion
  • alert
    • @@ -174,26 +241,17 @@ this.colorAutomaticTheme.addEventListener('change', this.setAutoTheme);
-### Источник значений токенов +### Откуда берутся значения -**Токены дизайн-системы** – это набор значений, которые определяют визуальный стиль наших компонентов. -Они хранятся в пакете [@koobiq/design-tokens](https://github.com/koobiq/design-tokens) и позволяют нам легко управлять стилем и обеспечивать его согласованность во всех компонентах. +**Токены дизайн-системы** — это значения, которые задают внешний вид наших компонентов. Они лежат в пакете [@koobiq/design-tokens](https://github.com/koobiq/design-tokens). -**Компонентные CSS-переменные** – это набор значений, которые используются в стилях наших компонентов. Они задаются на основе токенов и хранятся в репозитории `@koobiq/components`. -Это позволяет нам легко использовать токены в стилях компонентов и ускоряет разработку, в том числе проведение дизайн-ревью. +**Переменные компонентов** — это значения, которые используются в стилях компонентов. Они получены из токенов дизайн-системы и лежат в репозитории `@koobiq/components`, рядом с самими компонентами.
-
Обрати внимание
+
Обратите внимание
-На данный момент компонентные токены в пакете `@koobiq/design-tokens` больше не обновляются. +Токены компонентов в пакете `@koobiq/design-tokens` больше не обновляются и будут удалены в версии 4.0.0. Если они остались в ваших копиях `css-tokens.css`, `css-tokens-light.css`, `css-tokens-dark.css` или `css-tokens-font.css` — удалите их: компоненты везут свои значения сами.
- -### Планы - -- Проведем обновление наших компонентных CSS-переменных и будем использовать вместо них глобальные CSS-переменные нашей дизайн-системы напрямую, где необходимо. -- Удалим компонентные токены из пакета `@koobiq/design-tokens` в версии 4.0.0. -- Создадим страницу, где будут отображаться глобальные токены дизайн-системы с их визуальным представлением. -- Будем хранить компонентные токены в формате CSS-переменных в репозитории Angular-компонентов `@koobiq/components`. diff --git a/packages/docs-examples/components/core/index.ts b/packages/docs-examples/components/core/index.ts index 1c9332d952..9db8e7f7d6 100644 --- a/packages/docs-examples/components/core/index.ts +++ b/packages/docs-examples/components/core/index.ts @@ -1,9 +1,10 @@ import { NgModule } from '@angular/core'; +import { ThemeCssVariablesExample } from './theme-css-variables/theme-css-variables-example'; import { ThemeStaticSelectionExample } from './theme-static-selection/theme-static-selection-example'; -export { ThemeStaticSelectionExample }; +export { ThemeCssVariablesExample, ThemeStaticSelectionExample }; -const EXAMPLES = [ThemeStaticSelectionExample]; +const EXAMPLES = [ThemeCssVariablesExample, ThemeStaticSelectionExample]; @NgModule({ imports: EXAMPLES, diff --git a/packages/docs-examples/components/core/theme-css-variables/theme-css-variables-example.ts b/packages/docs-examples/components/core/theme-css-variables/theme-css-variables-example.ts new file mode 100644 index 0000000000..0eb7fa7afd --- /dev/null +++ b/packages/docs-examples/components/core/theme-css-variables/theme-css-variables-example.ts @@ -0,0 +1,37 @@ +import { ChangeDetectionStrategy, Component, inject } from '@angular/core'; +import { KbqButtonModule } from '@koobiq/components/button'; +import { KbqThemeService } from '@koobiq/components/core'; + +/** + * @title Theme values in your own styles + */ +@Component({ + selector: 'theme-css-variables-example', + imports: [KbqButtonModule], + template: ` +
+

Current theme: {{ themeService.colorScheme() }}

+ +
+ `, + styles: ` + .theme-css-variables-example__card { + padding: var(--kbq-size-l); + border: 1px solid var(--kbq-line-contrast-less); + border-radius: var(--kbq-size-border-radius); + background: var(--kbq-background-card); + color: var(--kbq-foreground-contrast); + } + + .theme-css-variables-example__caption { + margin: 0 0 var(--kbq-size-m); + color: var(--kbq-foreground-contrast-secondary); + } + `, + changeDetection: ChangeDetectionStrategy.OnPush +}) +export class ThemeCssVariablesExample { + // The app's shared service, so the switch flips the whole page — that is the point here: nothing + // in the styles above reacts to it explicitly, the variables simply resolve to the other theme. + protected readonly themeService = inject(KbqThemeService); +} diff --git a/packages/docs-examples/example-module.ts b/packages/docs-examples/example-module.ts index ff64a799f5..7366eabae6 100644 --- a/packages/docs-examples/example-module.ts +++ b/packages/docs-examples/example-module.ts @@ -1090,6 +1090,21 @@ export const EXAMPLE_COMPONENTS: {[id: string]: LiveExample} = { "primaryFile": "button-overview-example.ts", "importPath": "components/button" }, + "block-checkbox": { + "packagePath": "components/checkbox/block-checkbox", + "title": "Custom checkbox block", + "componentName": "BlockCheckboxExample", + "files": [ + "block-checkbox-example.ts" + ], + "localImportFiles": [], + "selector": "block-checkbox-example", + "additionalComponents": [ + "BlockCheckboxComponent" + ], + "primaryFile": "block-checkbox-example.ts", + "importPath": "components/checkbox" + }, "checkbox-indeterminate": { "packagePath": "components/checkbox/checkbox-indeterminate", "title": "Checkbox indeterminate", @@ -1367,6 +1382,19 @@ export const EXAMPLE_COMPONENTS: {[id: string]: LiveExample} = { "primaryFile": "content-panel-with-grid-example.ts", "importPath": "components/content-panel" }, + "theme-css-variables": { + "packagePath": "components/core/theme-css-variables", + "title": "Theme values in your own styles", + "componentName": "ThemeCssVariablesExample", + "files": [ + "theme-css-variables-example.ts" + ], + "localImportFiles": [], + "selector": "theme-css-variables-example", + "additionalComponents": [], + "primaryFile": "theme-css-variables-example.ts", + "importPath": "components/core" + }, "theme-static-selection": { "packagePath": "components/core/theme-static-selection", "title": "Theme static selection", @@ -7782,6 +7810,8 @@ return import('@koobiq/docs-examples/components/button'); return import('@koobiq/docs-examples/components/button'); case 'button-overview': return import('@koobiq/docs-examples/components/button'); + case 'block-checkbox': +return import('@koobiq/docs-examples/components/checkbox'); case 'checkbox-indeterminate': return import('@koobiq/docs-examples/components/checkbox'); case 'checkbox-multiline': @@ -7824,6 +7854,8 @@ return import('@koobiq/docs-examples/components/code-block'); return import('@koobiq/docs-examples/components/content-panel'); case 'content-panel-with-grid': return import('@koobiq/docs-examples/components/content-panel'); + case 'theme-css-variables': +return import('@koobiq/docs-examples/components/core'); case 'theme-static-selection': return import('@koobiq/docs-examples/components/core'); case 'absolute-date-formatter':