core-scripts

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

Требования

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

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

1. С помощью терминала перейти в директорию, в которой будут храниться проекты;
``

sh
$ cd projects


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

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


В директории

my-project

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

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

sh
$ cd my-project
$ npm run dev


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

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

./pages директории проекта.

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

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

По адресу http://localhost:3000/docs будет лежать документация компонентов, где будут описано предназначение компононента, его состояния и принимаемые им пропсы (от англ. properties). На данный момент есть только документация компонента кнопки по адресу http://localhost:3000/docs/button

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


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


import { Button } from '@asmy/core-design'


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

После импорта компонента его нужно вставить на страницу. Для этого поместите его на в объект страницы:`const NewPage = () => ( )

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

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


У компонентов есть пропсы, с помощью которых можно изменять их состояние. Пропсы бывают дефолтными, это те, которые компонент имеет сам по себе в зависимости от своего типа, и кастомными, это те, которые определяют разработчики. Кастомные пропсы каждого компонента свои, их количество, названия и их значиня устанавливают разработчики на этапе проектирования компонента, после обсуждения его с дизайнерами. Список доступных кастомных пропсов и их значений для каждого отдельного компонента можно будет найти на странице документации (пока только на http://localhost:3000/docs/button). 
Кроме того, ваш редактор кода может подсказывать какие пропсы имеет компонент и какие значения они могу принимать
![](http://s.csssr.ru/U31J879TR/20190423124655.jpg)

Пропсы для компонента записываются сразу после его названия внутри угловых скобок:``Пропсkind меняет тему кнопки, попробуйте ввести эту запись и посмотреть что получится.

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


Все компоненты, будут принимать пропс

css

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


Обратите внимание что пропс должен css принимать функцию

css

, которая в свою очеред принимает строку с описаными css правилами. Эту функцию нужно импортировать так же как компоненты на страницу где вы её собираетесь приминять:

import { css } from '@emotion/core'


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

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

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


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


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

    {props.children}

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

export { MyNewComponent } export default MyNewComponent`и стилями для него:`import { css } from '@emotion/core'

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

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

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

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

const OriginMyNewComponent= props =>


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

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


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:``

`$3`


Что бы использовать переменные темы в CSS вам нужно передать объект

props

 и указать путь до соответствующей переменной. Например, у вас есть следующие стили:


export default {
  base: css

color: blue;

,
}


но вы хотите что бы цвет был как

primary

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


export default {
  base: props => css

color: ${props.theme.colors.primary.origin};

,
}


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

Для манипуляций с цветами у нас используется библиотека color. Цвета в темах можно называть как угодно, но желательно максимально абстракто без ссылок на название цвета или состояний, например:

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

 и называются по методу генерации и его значения, например:


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(), }, } }``

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