Введение

Plasma UI – библиотека с открытым исходным кодом, в которую входят компоненты дизайн-системы Plasma и вспомогательные утилиты для создания смартапов на React или в коде сценария с помощью разметки AML.

Библиотека написана на Typescript, а компоненты реализованы с применением styled-components.

Установка

Plasma UI поддерживает версии React 16.8+ и styled-components ^5.1.1 (на данный момент 6-я версия не поддерживается из-за отсутствия необходимых типов). Ее можно использовать в существующем проекте.

Установите React, ReactDOM и styled-components:

npm install react react-dom styled-components@5.1.1

Использовать styled-components и typescript в проекте не обязательно.

Установите библиотеку компонентов, библиотеку токенов и библиотеку иконок:

npm install @salutejs/plasma-ui @salutejs/plasma-tokens @salutejs/plasma-icons

Настройка

Создайте компонент для подключения глобальных стилей и ротации цветовых тем:

GlobalStyle.tsx
import { createGlobalStyle } from 'styled-components';
import { salutejs_sber__dark } from '@salutejs/plasma-tokens/themes'; // Или один из списка: salutejs_eva__dark, salutejs_joy__dark, salutejs_eva__light, salutejs_sber__light
import {
text, // Цвет текста
background, // Цвет подложки
gradient, // Градиент
} from '@salutejs/plasma-tokens';

const DocumentStyle = createGlobalStyle`
html {
color: ${text};
background-color: ${background};
background-image: ${gradient};
}
`;
const ThemeStyle = createGlobalStyle(salutejs_sber__dark);

export const GlobalStyle = () => (
<>
<DocumentStyle />
<ThemeStyle />
</>
);

Корень приложения

В корне приложения вызовите компонент глобальных стилей GlobalStyle, а также с помощью DeviceThemeProvider подключите типографическую систему:

  • Если вы используете Create React App, делайте вызов внутри src/index.tsx.
  • Если вы используете Next.js, создайте файл pages/_app.tsx и подключите стили в нем.

Для корректной работы server side rendering приложение нужно обернуть SSRProvider;

index.tsx
import { DeviceThemeProvider, SSRProvider } from '@salutejs/plasma-ui';
import { GlobalStyle } from './GlobalStyle';
import { App } from './App';

ReactDOM.render(
<DeviceThemeProvider>
<SSRProvider>
<App />
<GlobalStyle />
</SSRProvider>
</DeviceThemeProvider>,
document.getElementById('root'),
);

Подробнее о стилях и типографике.

Использование

Не смотря на то, что все компоненты доступны из папки components, рекомендуется использовать их напрямую из пакета. Таким образом, обеспечивается работа tree shaking.

App.tsx
import { Container } from '@salutejs/plasma-ui/components/Grid';
import { Button } from '@salutejs/plasma-ui';

export default function App() {
return (
<Container>
<Button>Hello, Plasma!</Button>
</Container>
);
}

Библиотека предоставляет вспомогательную функциональность (utils, mixins, hocs), доступную в соответствующих директориях.

import { animatedScrollToX, addFocus, withAutoFocus } from '@salutejs/plasma-ui';

Подробную информацию ищите в документации по hocs, mixins и utils.