core-scripts

Утилита для развертывания нового проекта на Next.js c использованием библиотеки Core Design.

Требования

1. Для работы необходимо установить Node.js. Если не установлено, лучше установить LTS версию;
2. Git. На macOS и Ubuntu он уже должен быть предустановлен по-умолчанию;
3. Редактор кода. Советуем использовать VSCode;
4. Для удобной работы со стилями советуется установить плагины vscode-styled-components и eslint.

Для публикации кода в git нужно иметь ssh-ключ (как сделать описано в куче статей, например в этой) и добавить публичный ключ в настройках GitHub-a.

Стоит также задать имя и e-mail, которые будут указываться в коммитах:

``
$ git config --global user.email 'john@doe.com'
$ git config --global user.name 'John Doe'
`

Развертывание проекта

1. Подразумевается, что каждый проект должен храниться в отдельном репозитории. Поэтому следует начать с создания чистого репозитория на GitHub;
2. С помощью терминала перейти в директорию, в которой будут храниться проекты;

`sh
$ cd projects
`

3. Выполнить команду:

`sh
$ npx -p @csssr/core-scripts core-design create my-project
`

В терминале будут задаваться вопросы. На одном из этапов будет запрошен адрес репозитория (п. 1), в котором будет храниться код проекта.

В директории my-project развернётся новый проект. Его нужно открыть в редакторе кода.

Публикация кода

Можно сразу опубликовать код в репозиторий. Это делается таким образом:

`
$ cd my-project
$ git add .
$ git commit -m 'initial commit'
$ git push
`

Деплой

Также можно сразу опубликовать код в GitHub Pages. Для этого нужно выполнить эту команду в директории проекта:

`
$ npm run deploy
`

Подробнее про деплой на GitHub Pages рассказано в этом видео.

Процесс деплоя делится на 3 стадии:

1. Сборка (npm run build);
2. Экспорт (npm run export) — экспортируются страницы, указанные в next.config.js;
3. Деплой (./scripts/deploy.sh) — в файле есть комментарии о том, что вообще происходит.

Запуск сервера для разработки

1. Перейти в директорию с проектом и запустить команду:

`sh
$ cd my-project
$ npm run dev
`

Далее в браузере нужно перейти по адресу http://localhost:3000, где, если всё прошло успешно, будет находится страница примера.

Структура проекта

Для создания новой страницы нужно создать новый jsx-файл в директории ./pages директории проекта.

Название файла является также путем к странице. К примеру, если создать файл с именем blank.jsx, c примерно следующим содержанием:

`jsx
const NewPage = () =>

export default NewPage
`

то полученная страница будет находится по адресу http://localhost:3000/blank.

Создание прототипов

После создания страницы можно приступать к прототипированию. Если вам нужен какой либо-компонент из нашей библиотеки то его нужно импортировать на страницу прототипа, для этого в начале файла нужно добавить строчку:

`jsx
import { Button } from '@csssr/core-design'
`

Если вам нужно несколько компонентов, то укажите их названия через запятую.

После импорта компонента его нужно вставить на страницу. Для этого поместите его на в объект страницы:

`jsx
const NewPage = () => Кнопка

export default NewPage
`

Теперь у вас на странице появится компонент кнопки.

Изменение состояний компонентов

У компонентов есть пропсы, с помощью которых можно изменять их состояние. Пропсы бывают дефолтными, это те, которые компонент имеет сам по себе в зависимости от своего типа, и кастомными, это те, которые определяют разработчики. Кастомные пропсы каждого компонента свои, их количество, названия и их значиня устанавливают разработчики на этапе проектирования компонента, после обсуждения его с дизайнерами.

Кроме того, ваш редактор кода может подсказывать какие пропсы имеет компонент и какие значения они могу принимать
![](http://s.csssr.ru/U31J879TR/20190423124655.jpg)

Пропсы для компонента записываются сразу после его названия внутри угловых скобок:

`jsx
Кнопка
`

Пропс kind меняет тему кнопки, попробуйте ввести эту запись и посмотреть что получится.

Изменение стилей компонентов

Все компоненты, будут принимать пропс css. В этом пропсе можно будет описать css для компонента, если вам нужно что-то поменять в нём на месте, например:

`jsx
css={css
margin-top: 40px;
color: red;
outline: 1px solid red;
background-color: transparent;
}
>
Кнопка

`

Обратите внимание что пропс должен css принимать функцию css, которая в свою очеред принимает строку с описаными css правилами. Эту функцию нужно импортировать так же как компоненты на страницу где вы её собираетесь приминять:
import { css } from '@emotion/react'

Создание новых компонентов

Вы можете создать новый компонент командой:

`sh
$ npx -p @csssr/core-scripts core-design create-component _НазваниеКомпонента_
`

Название компонента должно быть написано в PascalCase. После исполнения команды в папке components будет создана директория с файлом компонента:

`jsx
import * as React from 'react'
import styled from '@emotion/styled'
import styles from './MyNewComponent.styles'
// import { Название_компонента_из_нашей_библиотеки_компонентов } from '@csssr/core-design'

const OriginMyNewComponent = props =>

const MyNewComponent = styled(OriginMyNewComponent)
${styles.base}

export { MyNewComponent }
export default MyNewComponent
`

и стилями для него:

`jsx
import { css } from '@emotion/react'

export default {
base: css
display: block;
,
}
`

В примере файла компонента OriginMyNewComponent нужен для описания верстки нового компоннета. В MyNewComponent указывается какие стили будут применятся для нового компонента. Стили делятся на логические блоки:

- base — для общих и статичных стилей компонента, т.e. тех, которые у компонента будут всегда не смотря на передаваемые ему пропсы;
- font — для стилей шрифтов;
- themes — для стилей описывающие компонент при различных темах;
- и любые другие кастомные блоки, которые вы считаете уместными (с течением времени этот список будет пополнятся укрепившимеся паттернами).

Если вам в новом компонент понадобится какой-либо другой компонент из дизайн-системы, вы можете его импортировать и вставить в вёрстку нового компонента, например:

`jsx
import { Button } from '@csssr/core-design'

const OriginMyNewComponent = props => (



)
`

Список всех компонентов дизайн системы и перечень их свойств вы можете найти на http://core-design.csssr.ru

Работа с темами

$3

Тема это объект в котором хранятся переменные цветов, брейкпоинтов, размеров. Все компоненты построены на основании этих переменных. Вот так выглядит дефолтная тема:

`jsx
const theme = {
colors: {
primary: {
origin: primaryOrigin.hex(),
darken15: primaryOrigin.darken(0.15).hex(),
},
secondary: {
origin: secondaryOrigin.hex(),
darken100: secondaryOrigin.darken(1).hex(),
},
},
baseSize: 16,
breakpoints: {
desktop: {
all: '@media (min-width: 1280px)',
m: '@media (min-width: 1360px) and (max-width: 1919px)',
s: '@media (min-width: 1280px) and (max-width: 1359px)',
},
tablet: {
all: '@media (min-width: 768px) and (max-width: 1279px)',
m: '@media (min-width: 1024px) and (max-width: 1279px)',
s: '@media (min-width: 768px) and (max-width: 1023px)',
},
mobile: {
all: '@media (max-width: 767px)',
},
below: {
desktop: '@media (max-width: 1279px)',
},
},
}
`

Где:

- colors — это различные цвета их оттенки, генерируемые из исходного значения цвета.
- baseSize— это размер шрифта у html тега страницы. Все расстояния и размеры в компонентах задаются c помощью относительной единицы rem.
- breakpoints — это медиа-выражения. Они поделены на несколько подтипов desktop, tablet, mobile и below. Первые три содержат в себе различные медиа-выражения для соответствующих устройств и разрешений экранов. Размеры s, m условны, их можно задвать произвольно, главное что бы они между собой не пересикались, all охватывает все разрешения подтипа. below содержит в себе медиавыражения, которые охватывают разрешения от заданного и ниже.

Если вы захотите поменять какой-либо из дефолтных параметров темы, то вам нужно будет создать новый файл темы в директории themes (если её ещё нет, то создайте в рутовской директории), а в новую переменную темы, скопировать туда старую и изменить нужные вам поля. После переменную новой темы нужно передать в пропс theme компонента Root, который находится в pages/_app.jsx:

`jsx



`

$3

Что бы использовать переменные темы в CSS вам нужно передать объект props и указать путь до соответствующей переменной. Например, у вас есть следующие стили:

`jsx
export default {
base: css
color: blue;
,
}
`

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

`jsx
export default {
base: props => css
color: ${props.theme.colors.primary.origin};
,
}
`

Работа с цветами

Для манипуляций с цветами у нас используется библиотека color. Цвета в темах можно называть как угодно, но желательно максимально абстракто без ссылок на название цвета или состояний, например: primary, secondary, danger, success и т.д. У каждого цевета должен быть объевлен origin, это его исходное состояние. Оттенки цветов генерируются из origin и называются по методу генерации и его значения, например:

`jsx
const primaryOrigin = color('#0076ff')

const theme = {
colors: {
primary: {
origin: primaryOrigin.hex(),
darken15: primaryOrigin.darken(0.15).hex(),
darken30: primaryOrigin.darken(0.3).hex(),
lighten45: primaryOrigin.lighten(0.45).hex(),
},
},
}
``

Список всех доступных методов находится тут