-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #19 from askorama/feature/orm-1550-3
Feature/ORM-1550-2
- Loading branch information
Showing
49 changed files
with
363 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,77 @@ | ||
import { Meta } from '@storybook/blocks'; | ||
|
||
<Meta title="Design Tokens/Theming" /> | ||
|
||
# Theming with Design Tokens | ||
|
||
Design tokens are a critical part of ensuring consistency and scalability in your design system. This guide shows how to avoid hardcoding values for colors, spacings, and typography by using tokens, while also supporting theme-specific styles using CSS custom properties. | ||
|
||
## Global styles | ||
|
||
We're using global styles that are available to all components and allow theme customization by exposing CSS custom properties. | ||
|
||
We use the `mapToCustomProperties(map)` mixin to apply custom properties from a map of key-value pairs. | ||
Theme switcher classes `.theme-light` and `.theme-dark` are used to apply the color tokens and they must be applied to the host element. | ||
As an extra layer of safety, to avoid any possible collisions with same named custom properties defined in the hosting application under the same class name, we use the `id^='orama-ui'` selector to scope the custom properties, therefore all shadow hosts must have an id starting with `orama-ui`. | ||
|
||
|
||
```css | ||
[id^='orama-ui'] { | ||
@include mapToCustomProperties($theme-light); // light theme is the default | ||
@include mapToCustomProperties($theme-typography); | ||
// other global styles... | ||
|
||
&.theme-dark { | ||
@include mapToCustomProperties($theme-dark); | ||
} | ||
} | ||
``` | ||
|
||
## Colors | ||
Instead of hardcoding color values, we use tokens defined in the global styles with support for themes. This approach allows you to easily switch between themes and maintain consistency across your application. | ||
|
||
When applying styles in your components, use the CSS custom properties with a fallback to the Sass function, that provide a fallback value from a predefined palette: | ||
|
||
```css | ||
.my-component { | ||
color: var(--text-color-primary, text-color(primary)); | ||
border: 1px solid var(--border-color-secondary, border-color(secondary)); | ||
background-color: var(--background-color-primary, background-color(primary)); | ||
|
||
} | ||
``` | ||
|
||
## Spacings | ||
|
||
Similar to colors, we define spacings using tokens: | ||
|
||
```css | ||
.my-component { | ||
margin: var(--spacing-s, $spacing-s); | ||
} | ||
``` | ||
|
||
We don't use the Sass function to fallback for spacings, as we don't expect to change them based on color scheme. We use plain sass variables for spacings. | ||
|
||
## Typography | ||
|
||
Typography values should also use tokens for consistency across themes: | ||
|
||
```css | ||
.my-component { | ||
font-size: var(--font-size-xs, $font-size-xs); | ||
line-height: var(--font-line-height-s, $font-line-height-s); | ||
} | ||
``` | ||
|
||
## Radius | ||
|
||
Border radius values should also use tokens for consistency across themes: | ||
|
||
```css | ||
.my-component { | ||
border-radius: var(--radius-s, $radius-s); | ||
} | ||
``` | ||
|
||
By following these practices, you ensure that your styles are consistent, maintainable, and easy to update across your entire application while supporting theme-specific custom properties. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
import { Meta } from '@storybook/blocks'; | ||
|
||
<Meta title="Usage/Frameworks/Angular" /> | ||
|
||
# Angular | ||
|
||
We offer an Angular version of every public component so you can use them in your Angular projects. | ||
|
||
## Installation | ||
|
||
To add the Orama UI Kit to your Angulat project, run: | ||
|
||
```bash | ||
npm install @orama/angular-components | ||
``` | ||
You can use pnpm or yarn if you prefer. | ||
|
||
## Usage | ||
|
||
In your `app.module.ts` file, import the component definition: | ||
|
||
```tsx | ||
import { ComponentLibraryModule } from '@orama/angular-components/dist/component-library' | ||
|
||
@NgModule({ | ||
declarations: [AppComponent], | ||
imports: [BrowserModule, AppRoutingModule, ComponentLibraryModule], | ||
providers: [], | ||
bootstrap: [AppComponent], | ||
schemas: [] | ||
}) | ||
``` | ||
|
||
In order to apply the global styles to your Angular project, you need to import the styles in your Angular project's styles.css or styles.scss | ||
|
||
```css | ||
@import '~@orama/angular-components/dist/component-library/styles.css'; | ||
``` | ||
|
||
You can then use the components you need in your project: | ||
|
||
```html | ||
<orama-chat-box | ||
[index]="{ | ||
api_key: 'your index api key', | ||
endpoint: 'your index endpoint', | ||
}" | ||
></orama-chat-box> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
import { Meta } from '@storybook/blocks'; | ||
|
||
<Meta title="Usage/Frameworks/React" /> | ||
|
||
# React | ||
|
||
We offer a React version of every public component so you can use them in your React projects. | ||
|
||
## Installation | ||
|
||
To add the Orama UI Kit to your React project, run: | ||
|
||
```bash | ||
npm install @orama/react-components | ||
``` | ||
You can use pnpm or yarn if you prefer. | ||
|
||
## Usage | ||
|
||
In your `App.tsx` file, import the component definition and use it in your JSX: | ||
|
||
```tsx | ||
import { defineCustomElements } from '@orama/react-components' | ||
|
||
void defineCustomElements() | ||
``` | ||
|
||
You can then import and use the components you need in your project: | ||
|
||
```tsx | ||
import { OramaChatBox } from '@orama/react-components' | ||
|
||
export const App = () => ( | ||
<OramaChatBox | ||
index={{ | ||
api_key: 'your index api key', | ||
endpoint: 'your index endpoint', | ||
}} | ||
/> | ||
) | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
import { Meta } from '@storybook/blocks'; | ||
|
||
<Meta title="Usage/Frameworks/Vue" /> | ||
|
||
# Vue | ||
|
||
We offer an Angular version of every public component so you can use them in your Angular projects. | ||
|
||
## Installation | ||
|
||
To add the Orama UI Kit to your Angulat project, run: | ||
|
||
```bash | ||
npm install @orama/vue-components | ||
``` | ||
You can use pnpm or yarn if you prefer. | ||
|
||
## Usage | ||
|
||
In your `app.module.ts` file, import the component definition: | ||
|
||
```tsx | ||
import { ComponentLibraryModule } from '@orama/angular-components/dist/component-library' | ||
|
||
@NgModule({ | ||
declarations: [AppComponent], | ||
imports: [BrowserModule, AppRoutingModule, ComponentLibraryModule], | ||
providers: [], | ||
bootstrap: [AppComponent], | ||
schemas: [] | ||
}) | ||
``` | ||
|
||
We have to make sure that the global styles are referenced in the Angular project. | ||
You can do this by importing the styles in your Angular project's styles.css or styles.scss | ||
|
||
```css | ||
@import '@orama/wc-components/dist/orama-ui/orama-ui.css'; | ||
``` | ||
|
||
You can then use the components you need in your project: | ||
|
||
```html | ||
<orama-chat-box | ||
[index]="{ | ||
api_key: 'your index api key', | ||
endpoint: 'your index endpoint', | ||
}" | ||
></orama-chat-box> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.