@csssr/core-scripts

core-scripts

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

Требования

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

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

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

$ git config --global user.email '[e-mail]'
$ git config --global user.name 'John Doe'

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

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

$ cd projects

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

$ 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 стадии:

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

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

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

$ cd my-project
$ npm run dev

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

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

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

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

const NewPage = () => (
  <div>Hello world!</div>
)

export default NewPage

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

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

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

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

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

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

const NewPage = () => (
  <Button>
    Кнопка
  </Button>
)

export default NewPage

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

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

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

Кроме того, ваш редактор кода может подсказывать какие пропсы имеет компонент и какие значения они могу принимать

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

  <Button kind='secondary'>
    Кнопка
  </Button>

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

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

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

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

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

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

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

$ npx -p @csssr/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 '@csssr/core-design'

const OriginMyNewComponent= props =>
  <div className={props.className}>
    {props.children}
  </div>

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 '@csssr/core-design'

const OriginMyNewComponent= props =>
  <div className={props.className}>
    <Button>Кнопка</Button>
  </div>

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

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

Объект темы

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

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:

<Root theme={myNewtheme}>
  <Component {...pageProps} />
</Root>

Использование переменных темы

Что бы использовать переменные темы в 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(),
    },
  }
}

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