@asmy/core-scripts v0.4.4

core-scripts

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

Требования

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

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

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

$ cd projects

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

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

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

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

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

$ 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 = () => (
  <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 @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 =>
  <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 '@asmy/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(),
    },
  }
}

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