diff --git a/.editorconfig b/.editorconfig index 428ef454..55c6bda2 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,6 +11,8 @@ insert_final_newline = true [*.md] trim_trailing_whitespace = false +indent_style = space +indent_size = 2 [.nvmrc] insert_final_newline = false diff --git a/.eslintrc.js b/.eslintrc.js index f903e9a0..dbe95b59 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -1,7 +1,6 @@ -const noUnusedVars = [ - 'error', - {ignoreRestSiblings: true, argsIgnorePattern: '^_.*$'}, -]; +const noUnusedVars = ['error', { ignoreRestSiblings: true, argsIgnorePattern: '^_.*$' }]; + +const silence = require.resolve("./lint/silence-typescript.js") module.exports = { parser: '@typescript-eslint/parser', @@ -26,7 +25,7 @@ module.exports = { 'plugin:import/errors', 'plugin:import/warnings', 'plugin:import/typescript', - 'silence', + silence, 'plugin:prettier/recommended', 'plugin:@typescript-eslint/recommended', 'prettier', @@ -38,14 +37,8 @@ module.exports = { }, rules: { 'no-unused-vars': noUnusedVars, - 'max-lines': [ - 'error', - {max: 1500, skipBlankLines: true, skipComments: true}, - ], - 'max-lines-per-function': [ - 'error', - {max: 110, skipBlankLines: true, skipComments: true}, - ], + 'max-lines': ['error', { max: 1500, skipBlankLines: true, skipComments: true }], + 'max-lines-per-function': ['error', { max: 110, skipBlankLines: true, skipComments: true }], 'no-console': 'off', 'new-cap': [ 'error', @@ -53,29 +46,22 @@ module.exports = { capIsNewExceptions: ['Deferred', 'Event'], }, ], - 'spaced-comment': [ - 'error', - 'always', - {markers: ['#region'], exceptions: ['#endregion']}, - ], - 'lines-between-class-members': [ - 'error', - 'always', - {exceptAfterSingleLine: true}, - ], + 'spaced-comment': ['error', 'always', { markers: ['#region'], exceptions: ['#endregion'] }], + 'lines-between-class-members': ['error', 'always', { exceptAfterSingleLine: true }], 'no-prototype-builtins': 'off', 'no-throw-literal': 'off', 'prefer-promise-reject-errors': 'off', 'no-shadow': 'off', 'prefer-template': 'error', 'require-await': 'error', - curly: 'error', + 'curly': 'error', '@typescript-eslint/class-name-casing': 'off', 'no-useless-constructor': 'off', // see @typescript-eslint/no-useless-constructor '@typescript-eslint/no-useless-constructor': 'error', 'no-unused-expressions': 'off', // плохо работает с ts (optional chaining) '@typescript-eslint/no-unused-expressions': 'error', + 'no-use-before-define': 'off', '@typescript-eslint/no-use-before-define': 'off', '@typescript-eslint/no-unused-vars': noUnusedVars, '@typescript-eslint/explicit-member-accessibility': 'off', @@ -86,9 +72,9 @@ module.exports = { '@typescript-eslint/no-var-requires': 'off', '@typescript-eslint/naming-convention': [ 'warn', - {selector: 'default', format: ['camelCase']}, + { selector: 'default', format: ['camelCase'] }, - {selector: 'variableLike', format: ['camelCase']}, + { selector: 'variableLike', format: ['camelCase'] }, { selector: 'variable', format: ['camelCase', 'UPPER_CASE', 'PascalCase'], @@ -98,7 +84,7 @@ module.exports = { format: ['camelCase'], leadingUnderscore: 'allow', }, - {selector: 'memberLike', format: ['camelCase']}, + { selector: 'memberLike', format: ['camelCase'] }, { selector: 'memberLike', modifiers: ['private'], @@ -106,13 +92,17 @@ module.exports = { leadingUnderscore: 'allow', }, - {selector: 'typeLike', format: ['PascalCase']}, - {selector: 'typeParameter', format: ['PascalCase']}, + { selector: 'typeLike', format: ['PascalCase'] }, + { selector: 'typeParameter', format: ['PascalCase'] }, { selector: 'interface', format: ['PascalCase'], - custom: {regex: '^I[A-Z]', match: false}, + custom: { regex: '^I[A-Z]', match: false }, + }, + { + selector: ['classProperty', 'objectLiteralProperty', 'typeProperty'], // могут быть какими угодно + format: null, }, ], '@typescript-eslint/interface-name-prefix': 'off', @@ -122,7 +112,7 @@ module.exports = { 'unicorn/catch-error-name': [ 'error', { - caughtErrorsIgnorePattern: '^(error|err)$', + ignore: ['^(error|err)$'], }, ], 'unicorn/prefer-reflect-apply': 'off', // можно дропнуть вместе с поддержкой ie11 @@ -136,6 +126,28 @@ module.exports = { 'simple-import-sort/imports': 'error', 'simple-import-sort/exports': 'error', + + 'no-param-reassign': [ + "warn", + { + props: true, + ignorePropertyModificationsFor: [ + 'acc', + 'accumulator', + 'e', + 'ctx', + 'context', + 'req', + 'request', + 'res', + 'response', + '$scope', + 'staticContext', + 'toValue', + 'destination', + ], + }, + ], }, overrides: [ { diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs new file mode 100644 index 00000000..cd295c95 --- /dev/null +++ b/.git-blame-ignore-revs @@ -0,0 +1,2 @@ +# style: add @vkontakte/prettier-config +f756c56311383dfe6f6d32d718fa04c3f63cea7c \ No newline at end of file diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..976a528f --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +.github/ @VKCOM/vk-sec +src/interfaces/general @VKCOM/vkui-design +src/interfaces/namespaces @VKCOM/vkui-design +src/themeDescriptions/base @VKCOM/vkui-design +src/themeDescriptions/common @VKCOM/vkui-design +src/themeDescriptions/index.ts @VKCOM/vkui-design diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..d9b72592 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,12 @@ +Перед отправкой этого реквеста на ревью убедитесь, что: + +- в вашей ветке работает сборка (`npm run build:local`), +- в вашей ветке проходят тесты (`npm test`), +- в вашей ветке проходит линтер (`npm run lint`), некоторые ошибки можно автоматически поправить с помощью `npm run lint:fix`, +- покрытие тестов не ниже минимального значения, +- если вы вносите изменения в задокументированные части библиотеки, + ваш pull request содержит обновления документации, +- если вы вносите изменения в сами токены, вы + согласовали их с дизайнерами. + +[Подробнее о внесении изменений в репозиторий токенов](https://github.com/VKCOM/vkui-tokens/blob/master/CONTRIBUTING.md) diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..8f026ba0 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,38 @@ +version: 2 +updates: + - package-ecosystem: 'npm' + directory: '/' + schedule: + interval: 'daily' + allow: + - dependency-type: 'direct' + open-pull-requests-limit: 10 + groups: + react: + patterns: + - 'react' + - 'react-dom' + - '@types/react' + - '@types/react-dom' + eslint: + patterns: + - 'eslint*' + jest: + patterns: + - 'jest*' + - '@types/jest*' + - 'babel-jest' + prettier: + patterns: + - 'prettier' + - '@vkontakte/prettier-config' + reviewers: + - 'VKCOM/vk-sec' + - package-ecosystem: 'github-actions' + # Workflow files stored in the + # default location of `.github/workflows` + directory: '/' + schedule: + interval: 'daily' + reviewers: + - 'VKCOM/vk-sec' diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index 2871c025..fc220435 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -4,14 +4,19 @@ on: branches: - master +permissions: write-all + jobs: coverage: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v1 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: '14' - - uses: artiomtr/jest-coverage-report-action@v2.0-rc.1 + node-version: 18 + cache: 'yarn' + - uses: artiomtr/jest-coverage-report-action@v2 with: github-token: ${{ secrets.GITHUB_TOKEN }} + annotations: coverage + package-manager: yarn diff --git a/.github/workflows/figma.yml b/.github/workflows/figma.yml new file mode 100644 index 00000000..c2b99a73 --- /dev/null +++ b/.github/workflows/figma.yml @@ -0,0 +1,36 @@ +name: 'Figma updates' +on: + schedule: + - cron: '0 10 * * *' # every day at 10:00 + +jobs: + close-issues: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '18' + - run: yarn install + + - name: Figma styles VK to json + uses: VKCOM/gh-actions/vkui-tokens/token-base@main + with: + token: ${{ secrets.FIGMA_TOKEN }} + file_key: ${{ secrets.FIGMA_VK_FILE_KEY }} + output_file_name: src/themeDescriptions/base/figma/vk.json + + - run: yarn test -u + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.DEVTOOLS_GITHUB_TOKEN }} + title: Figma updates + branch: github-actions/build/figma/token-updates + commit-message: 'build(figma): token updates' + body: Automated figma updates + labels: dependencies, figma diff --git a/.github/workflows/publish_dev.yml b/.github/workflows/publish_dev.yml index 0010dee5..0f5e15b1 100644 --- a/.github/workflows/publish_dev.yml +++ b/.github/workflows/publish_dev.yml @@ -8,12 +8,12 @@ jobs: name: Publish development release from git commit SHA runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 18 registry-url: 'https://registry.npmjs.org' - - run: npm ci + - run: yarn install --frozen-lockfile --ignore-scripts - name: Assigning new version run: npm version prerelease --commit-hooks=false --git-tag-version=false --preid=dev-${GITHUB_SHA:0:6} - name: Publishing release diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml new file mode 100644 index 00000000..2d21b94d --- /dev/null +++ b/.github/workflows/publish_docs.yml @@ -0,0 +1,47 @@ +name: Publish VKUI Tokens documentation to GitHub Pages + +on: + push: + branches: + - master + +permissions: + contents: read + pages: write + id-token: write + +jobs: + deploy: + name: Deploy + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Build main app + uses: actions/setup-node@v4 + with: + node-version: 18 + - run: yarn install --frozen-lockfile --ignore-scripts + - run: npm run build + + - name: Prepare tokens data + run: npm run docs:prepare-data + + - name: Build docs app + run: npm run docs:build + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: './docs/dist' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/publish_from_git.yml b/.github/workflows/publish_from_git.yml index fbdaeff2..5c917043 100644 --- a/.github/workflows/publish_from_git.yml +++ b/.github/workflows/publish_from_git.yml @@ -8,12 +8,12 @@ jobs: name: Publish release-candidate from package.json version runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v1 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 18 registry-url: 'https://registry.npmjs.org' - - run: npm ci + - run: yarn install --frozen-lockfile --ignore-scripts - name: Publishing release run: npm run publish:dist env: diff --git a/.github/workflows/publish_release.yml b/.github/workflows/publish_release.yml index 801e8f2d..ab0949d0 100644 --- a/.github/workflows/publish_release.yml +++ b/.github/workflows/publish_release.yml @@ -7,38 +7,39 @@ on: - published jobs: - publish_release: - name: Publish release - if: "!github.event.release.prerelease" + publish: + name: Publish runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - - name: Use Node.js 14 - uses: actions/setup-node@v2 + - name: Use Node.js + uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 18 cache: 'npm' registry-url: https://registry.npmjs.org/ - - run: npm ci + - run: yarn install --frozen-lockfile --ignore-scripts - run: npm run publish:latest + if: '!github.event.release.prerelease' env: NODE_AUTH_TOKEN: ${{secrets.NPMJS_PUBLISH_TOKEN}} - - publish_prerelease: - name: Publish pre-release - if: "github.event.release.prerelease" - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - - name: Use Node.js 14 - uses: actions/setup-node@v2 - with: - node-version: 14 - cache: 'npm' - registry-url: https://registry.npmjs.org/ - - run: npm ci - run: npm run publish:dist + if: 'github.event.release.prerelease' env: NODE_AUTH_TOKEN: ${{secrets.NPMJS_PUBLISH_TOKEN}} + + - uses: vimtor/action-zip@v1 + with: + files: dist/ + dest: build.zip + - name: Upload Release Asset + id: upload-release-asset + uses: actions/upload-release-asset@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + upload_url: ${{ github.event.release.upload_url }} + asset_path: ./build.zip + asset_name: build.zip + asset_content_type: application/zip diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2324dfc2..f7da4736 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -10,28 +10,29 @@ jobs: lint: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: '14' - - run: npm ci + node-version: '18' + - run: yarn install --frozen-lockfile --ignore-scripts - run: npm run lint test: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: '14' - - run: npm ci + node-version: '18' + - run: yarn install --frozen-lockfile --ignore-scripts - run: npm run test:ci build: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 with: - node-version: '14' - - run: npm ci + node-version: '18' + - run: yarn install --frozen-lockfile --ignore-scripts - run: npm run build - + - run: npm run docs:prepare-data + - run: npm run docs:build diff --git a/.gitignore b/.gitignore index e5ba5065..6e83cdb5 100644 --- a/.gitignore +++ b/.gitignore @@ -6,13 +6,23 @@ node_modules/ !/src/ !/demo !/assets +!/lint !/.github /**/*.d.ts /**/*.js +!/tasks +!/tasks/**/*.js +!/lint/*.js !.eslintrc.js !jest.config.js +!.prettierrc.js .yarnclean .DS_Store .idea ./dist/ junit.xml +!/docs/ +docs/src/**/*.d.ts +docs/public/**/*.json +docs/dist/ +!.husky diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 00000000..765baae3 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/usr/bin/env sh +. "$(dirname -- "$0")/_/husky.sh" + +yarn pre-commit diff --git a/.npmrc b/.npmrc index a36868b8..efaaee83 100644 --- a/.npmrc +++ b/.npmrc @@ -4,3 +4,5 @@ git-tag-version=false save-exact=true package-lock=true tag=rc + +engine-strict=true diff --git a/.nvmrc b/.nvmrc index 19c7bdba..25bf17fc 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -16 \ No newline at end of file +18 \ No newline at end of file diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index fa381296..00000000 --- a/.prettierrc +++ /dev/null @@ -1,9 +0,0 @@ -{ - "singleQuote": true, - "trailingComma": "all", - "arrowParens": "always", - "useTabs": true, - "bracketSpacing": false, - "tabWidth": 4, - "parser": "typescript" -} diff --git a/.prettierrc.js b/.prettierrc.js new file mode 100644 index 00000000..5efb34da --- /dev/null +++ b/.prettierrc.js @@ -0,0 +1 @@ +module.exports = require('@vkontakte/prettier-config').createConfig(); diff --git a/.yarnrc b/.yarnrc new file mode 100644 index 00000000..cc21f88f --- /dev/null +++ b/.yarnrc @@ -0,0 +1,4 @@ +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. +# yarn lockfile v1 + +frozen-lockfile true diff --git a/.yarnrc.yml b/.yarnrc.yml new file mode 100644 index 00000000..3186f3f0 --- /dev/null +++ b/.yarnrc.yml @@ -0,0 +1 @@ +nodeLinker: node-modules diff --git a/CHANGELOG.OLD.md b/CHANGELOG.OLD.md index 56462077..828c0ba0 100644 --- a/CHANGELOG.OLD.md +++ b/CHANGELOG.OLD.md @@ -1,141 +1,165 @@ # **CHANGELOG (Архивная версия)** ## 4.0.0 -* **Перешли на релизы через [GitHub](https://github.com/VKCOM/vkui-tokens/releases). Все следующие релизы будут описываться там!** + +- **Перешли на релизы через [GitHub](https://github.com/VKCOM/vkui-tokens/releases). Все следующие релизы будут описываться там!** **BREAKING CHANGES** -* Провели рефакторинг дизайн-системы в рамках объединения **VKUI** и **Paradigm**: удалили ненужные, добавили новые, поменяли названия старых. + +- Провели рефакторинг дизайн-системы в рамках объединения **VKUI** и **Paradigm**: удалили ненужные, добавили новые, поменяли названия старых. Изменения можно найти в [таблице](https://docs.google.com/spreadsheets/d/10DBlAGM68KyZ1DHtr-xKy-JDDqrsWaItF67fo7-hOy4/edit#gid=314413476) - -* Изменили формат описания адаптивных токенов: теперь идём не от `viewport` (`touch`,`desktop`), а +- Изменили формат описания адаптивных токенов: теперь идём не от `viewport` (`touch`,`desktop`), а от состояний самого токена: `regular`, `compact`, `large` и т.д. Указывать состояния, отличные от `regular` нужно указывать тогда, и только тогда, когда они действительно отличаются. - + Для проектов использующих уже медиаквери и вьюпорты (paradigm-проекты) при генерации сделан маппинг с помощью переменной `breakpoints`. - -* Переписали старую генерацию `scss`, `css`, `less`, `styl` форматов с нуля. Теперь покрыли это **автотестами**: можно зайти в тесты и посмотреть как в каждом формате обробатывается каждый вид переменной - _цвет, групповая переменная (шрифты), адаптивная, медиа_ и так далее. + +- Переписали старую генерацию `scss`, `css`, `less`, `styl` форматов с нуля. Теперь покрыли это **автотестами**: можно зайти в тесты и посмотреть как в каждом формате обробатывается каждый вид переменной + _цвет, групповая переменная (шрифты), адаптивная, медиа_ и так далее. Теперь поддержка будет прозрачнее и добавление новых конструкций в процессоры не будет проблемой. - - Важно: во время переписи и из-за того, что формат адаптивных переменных сильно поменялся, то подход с ними в процессорах css тоже. + + Важно: во время переписи и из-за того, что формат адаптивных переменных сильно поменялся, то подход с ними в процессорах css тоже. Теперь везде, кроме нативного css, переменные не переопределяются автоматически через @media-query. Чтобы эту мехнику получить — нужно css файлы из `themes/${themName}/cssVars/declarations`. -* Сделали единый базовый интерфейс дизайн-системы и описали в нём тему для `paradigm` (светлый и тёмный) и `vk` (пока только светлый). -* Сделали расширение базового интерфейса для Paradigm тем и портальной специфики. -* Порефакторили подход к генерации форматов: - * Экспортируем в пакете в папку `build` все функции с помощью которых можно собрать любой вид темы. Теперь можно по описанию темы собрать её - где-то в своём проекте, а не пользоваться только готовыми отсюда - * Сделали так, чтобы любой формат темы можно было собрать хоть из одной переменной. Теперь можно легко иметь в проекте локальные переменные не связанные с дизайн-системой, но в привычном формате. -* Изменили файловую структуру при экспорте библиотеки — теперь вместо того чтобы все собранные темы попадали в `root` + +- Сделали единый базовый интерфейс дизайн-системы и описали в нём тему для `paradigm` (светлый и тёмный) и `vk` (пока только светлый). +- Сделали расширение базового интерфейса для Paradigm тем и портальной специфики. +- Порефакторили подход к генерации форматов: + - Экспортируем в пакете в папку `build` все функции с помощью которых можно собрать любой вид темы. Теперь можно по описанию темы собрать её + где-то в своём проекте, а не пользоваться только готовыми отсюда + - Сделали так, чтобы любой формат темы можно было собрать хоть из одной переменной. Теперь можно легко иметь в проекте локальные переменные не связанные с дизайн-системой, но в привычном формате. +- Изменили файловую структуру при экспорте библиотеки — теперь вместо того чтобы все собранные темы попадали в `root` , они попадают в `root/themes`. Это важно, поскольку теперь в экспорте ещё есть разные полезные функции помимо тем. - -* Поработали над тёмной темой сделали основную базовую тёмную тему и отдельно темные цвета -* Удалили `flat` темы -* Удалили `subthemes` везде -* название пакета `@vkontakte/vkui-tokens` +- Поработали над тёмной темой сделали основную базовую тёмную тему и отдельно темные цвета +- Удалили `flat` темы +- Удалили `subthemes` везде +- название пакета `@vkontakte/vkui-tokens` ## 3.2.0 -* Добавили темы `octaviusDark` и `homeDark` -* Сделали правки в типографике в `calendar` -* Добавили экспорт объявления цветов css-vars в js и в виде строки. + +- Добавили темы `octaviusDark` и `homeDark` +- Сделали правки в типографике в `calendar` +- Добавили экспорт объявления цветов css-vars в js и в виде строки. ## 3.1.0 -* Обновили тему `otvet`, добавили тёмный вариант `otvetDark` -* Аккуратно поправили вывод в генерации стилей (убрали ненужные строчки) + +- Обновили тему `otvet`, добавили тёмный вариант `otvetDark` +- Аккуратно поправили вывод в генерации стилей (убрали ненужные строчки) ## 3.0.0 -* Добавили новый вид темы `cssVars` она объявляет переменные как нативные css-custom-properties в `cssVars/${themeName}/declarations/index.css`. Там сразу сделаны изменения переменных по breakpoints, а также добавлены специальные классы для форсированного включения нужного брейкпоинта. Демо можно найти [тут](demo/example-adaptive-css-vars-theme.html); -* Также сделали компиляцию объекта темы (в `cssVars/${themeName}/theme/index`) (`ts`, `js`, `json` форматы) в где каждая переменная представлена как `{name: '--paradigm--x1', value: 'var(--paradigm--x1, 4px)'}` -* Добавили тестирование снапшотами на каждую тему (теперь любое изменение в теме вызовет падение тестов с полным дифом каждой переменной, нужно будет апрувить изменения, обновляя снапшоты (`npm t -- -u`)) -* Добавили расчёт тестового покрытия (`coverage`) в репозитории -* Для удобной миграции на `cssVars` тему в `${themeName}/cssVars/theme/fallbacks` добавлены темы, процессоров, которые ссылаются на уже нативные CSS-переменные. То есть `$size-base: 4px` -> `$size-base: var(--paradigm--size_base, 4px)` -* js,json,ts добавили поле `themeType: 'root' | 'flat' | 'pixelify' | 'cssVars'`, чтобы в runtime понимать, с каким видом темы сейчас работаем -* В `${themeName}/cssVars/declarations` помимо `index.css` есть также файлы `onlyRoot.css` (только рутовое определение переменных без, адаптивности), а также `modern.css` (используются нативные mixin ы в css (читай про @apply)) -* **BREAKING CHANGES**: удалили генерацию `css` файлов во всех (они были невалидные, поэтому врятли кто-то ими польовался), кроме `cssVars` видах тем. Теперь чистый нативный css можно заимпортить тут: `cssVars/${themeName}/declarations/index.css`. -* **BREAKING CHANGES**: в темах, в адаптивных переменных больше нет `default` состояния, вместо этого теперь там указан конкретный `viewport` (например, `touch` или `desktopS`). Это было сделано, так как default был по-сути алисом на `touch` viewport, что вызывало неконсистентые состояния, при использовании темы без `touch` брейкпоинта. Это нам дало следующие возможности: теперь можно создавать темы с любым подножеством брейкпоинтов, например: `['desktopS, 'desktopM']` - будет тема из двух десктопных брейкпоинтов. На самом деле это должно затронуть только описание тем, а также типы и `ts`, `js`, `json` форматы. Выходные файлы других форматов не изменились. `flat` темы всех форматов остались прежними. -* **BREAKING CHANGES**: подняли мажор `csstype` (единственная `prod` зависимость для `npm` у токенов). Теперь `3.0.7`. (Может вызывать нюансы в типах при обновлении). +- Добавили новый вид темы `cssVars` она объявляет переменные как нативные css-custom-properties в `cssVars/${themeName}/declarations/index.css`. Там сразу сделаны изменения переменных по breakpoints, а также добавлены специальные классы для форсированного включения нужного брейкпоинта. Демо можно найти [тут](demo/example-adaptive-css-vars-theme.html); +- Также сделали компиляцию объекта темы (в `cssVars/${themeName}/theme/index`) (`ts`, `js`, `json` форматы) в где каждая переменная представлена как `{name: '--paradigm--x1', value: 'var(--paradigm--x1, 4px)'}` +- Добавили тестирование снапшотами на каждую тему (теперь любое изменение в теме вызовет падение тестов с полным дифом каждой переменной, нужно будет апрувить изменения, обновляя снапшоты (`npm t -- -u`)) +- Добавили расчёт тестового покрытия (`coverage`) в репозитории +- Для удобной миграции на `cssVars` тему в `${themeName}/cssVars/theme/fallbacks` добавлены темы, процессоров, которые ссылаются на уже нативные CSS-переменные. То есть `$size-base: 4px` -> `$size-base: var(--paradigm--size_base, 4px)` +- js,json,ts добавили поле `themeType: 'root' | 'flat' | 'pixelify' | 'cssVars'`, чтобы в runtime понимать, с каким видом темы сейчас работаем +- В `${themeName}/cssVars/declarations` помимо `index.css` есть также файлы `onlyRoot.css` (только рутовое определение переменных без, адаптивности), а также `modern.css` (используются нативные mixin ы в css (читай про @apply)) +- **BREAKING CHANGES**: удалили генерацию `css` файлов во всех (они были невалидные, поэтому врятли кто-то ими польовался), кроме `cssVars` видах тем. Теперь чистый нативный css можно заимпортить тут: `cssVars/${themeName}/declarations/index.css`. +- **BREAKING CHANGES**: в темах, в адаптивных переменных больше нет `default` состояния, вместо этого теперь там указан конкретный `viewport` (например, `touch` или `desktopS`). Это было сделано, так как default был по-сути алисом на `touch` viewport, что вызывало неконсистентые состояния, при использовании темы без `touch` брейкпоинта. Это нам дало следующие возможности: теперь можно создавать темы с любым подножеством брейкпоинтов, например: `['desktopS, 'desktopM']` - будет тема из двух десктопных брейкпоинтов. На самом деле это должно затронуть только описание тем, а также типы и `ts`, `js`, `json` форматы. Выходные файлы других форматов не изменились. `flat` темы всех форматов остались прежними. +- **BREAKING CHANGES**: подняли мажор `csstype` (единственная `prod` зависимость для `npm` у токенов). Теперь `3.0.7`. (Может вызывать нюансы в типах при обновлении). ## 2.6.1 -* Для календарной темы обновили `thumbnailColor` + +- Для календарной темы обновили `thumbnailColor` ## 2.6.0 -* В основные темы перенесены переменные из subthemes - `colorBgPlaceholder` (цвет подложки) и `colorIconAccent` (цвет акцентированной иконки) -* Добавлен токен `colorBgPromo` для задания цвета фона промо элементов и панелей (плашек) + +- В основные темы перенесены переменные из subthemes - `colorBgPlaceholder` (цвет подложки) и `colorIconAccent` (цвет акцентированной иконки) +- Добавлен токен `colorBgPromo` для задания цвета фона промо элементов и панелей (плашек) ## 2.5.0 -* добавили переменную `sizeControlCheckBorderRadius` — _Радиус скругления чекбоксов_ -* исправили наследование `calendar` темы от octavius (больше не попадают переменные из подтем) -* удалили подтемы из календарной темы, вместо этого создали новую тему `calendarDark` с корректным интерфейсом + +- добавили переменную `sizeControlCheckBorderRadius` — _Радиус скругления чекбоксов_ +- исправили наследование `calendar` темы от octavius (больше не попадают переменные из подтем) +- удалили подтемы из календарной темы, вместо этого создали новую тему `calendarDark` с корректным интерфейсом ## 2.4.0 -* добавили тему для Облака `cloud` -* добавили переменные (и их описания) во все темы `fontFamilyAccent`, `fontWeightAccent`, `fontWeightAccentBold` -* сделали чуть более корректное наследование тем от `octavius` (чтобы не попадали в тему переменные subthemes, которые deprecated) -* Исправили генерацию customMedia (убрали перекрытие breakpoints) + +- добавили тему для Облака `cloud` +- добавили переменные (и их описания) во все темы `fontFamilyAccent`, `fontWeightAccent`, `fontWeightAccentBold` +- сделали чуть более корректное наследование тем от `octavius` (чтобы не попадали в тему переменные subthemes, которые deprecated) +- Исправили генерацию customMedia (убрали перекрытие breakpoints) ## 2.3.1 -* Изменили скругление кнопок до 8px для календарных тем + +- Изменили скругление кнопок до 8px для календарных тем ## 2.3.0 -* Добавляeтся токен "checkBoxBorderColor" для задания цвета у чекбоксов + +- Добавляeтся токен "checkBoxBorderColor" для задания цвета у чекбоксов ## 2.2.1 -* Добавляются токен "sizePromoArrowWidth" для корректного отображения стрелки в 2kit + +- Добавляются токен "sizePromoArrowWidth" для корректного отображения стрелки в 2kit ## 2.2.0 -* Добавляются токен на размер стрелки тултипа и токен для цвета новостного метатреда + +- Добавляются токен на размер стрелки тултипа и токен для цвета новостного метатреда ## 2.1.0 -* Добавляется генерация мапки со всеми переменными после миксина для SASS-файлов. + +- Добавляется генерация мапки со всеми переменными после миксина для SASS-файлов. ## 2.0.0 -* имя пакета теперь снова `@paradigm/tokens` . `@paradigm/themes` больше никогда публиковаться не будет. -* Добавлен общий интерфейс темы, от которой отнаследованы все остальные темы. -* Добавлен общий интерфейс ОПИСАНИЯ темы. (Теперь создавая тему у вас будет тип, с которым невозможно будет забыть указать что-либо). Непонятно почему недостаточно предыдущего пункта? — скорее всего вы никогда не работали в токенах. -* Процесс преобразования описания темы в полноценную тему полностью выводится из типов. И покрыт автотестами. -* Добавили и настроили линтер -* Настроили CI (проверяем линтер, jest и сборку) -* Добавили функцию хелпер `getStateFunctions`, которая добавит к теме функции, позволяющие динамически создавать `hover`, `active` состояния. + +- имя пакета теперь снова `@paradigm/tokens` . `@paradigm/themes` больше никогда публиковаться не будет. +- Добавлен общий интерфейс темы, от которой отнаследованы все остальные темы. +- Добавлен общий интерфейс ОПИСАНИЯ темы. (Теперь создавая тему у вас будет тип, с которым невозможно будет забыть указать что-либо). Непонятно почему недостаточно предыдущего пункта? — скорее всего вы никогда не работали в токенах. +- Процесс преобразования описания темы в полноценную тему полностью выводится из типов. И покрыт автотестами. +- Добавили и настроили линтер +- Настроили CI (проверяем линтер, jest и сборку) +- Добавили функцию хелпер `getStateFunctions`, которая добавит к теме функции, позволяющие динамически создавать `hover`, `active` состояния. ## 1.18.0 -* Обновили цвет вк по их брендбуку + +- Обновили цвет вк по их брендбуку ## 1.17.0 -* Добавили тему Задач Mail.ru -* Добавили темную тему для календаря + +- Добавили тему Задач Mail.ru +- Добавили темную тему для календаря ## 1.16.1 -* Поправили размеры шрифта в теме `calendar` + +- Поправили размеры шрифта в теме `calendar` ## 1.16.0 -* Добавили переменные `sizeBadge[XS|S|M|L|XL]` + +- Добавили переменные `sizeBadge[XS|S|M|L|XL]` ## 1.15.0 -* добавили переменную paddingControlSelectIcon 
 + +- добавили переменную paddingControlSelectIcon ## 1.14.0 -* добавили переменную colorButtonContrastBg 
 -* добавили переменную colorCategoryToMyself в тему октавиуса + +- добавили переменную colorButtonContrastBg +- добавили переменную colorCategoryToMyself в тему октавиуса ## 1.13.0 -* Обновили цвета с оттенками серого во всех темах -* Обновили тему `home` (Относледовали от `octavius` и добавили токенов) + +- Обновили цвета с оттенками серого во всех темах +- Обновили тему `home` (Относледовали от `octavius` и добавили токенов) ## 1.12.0 -* Добавили в тему календаря шрифт `MailSans` + +- Добавили в тему календаря шрифт `MailSans` ## 1.11.0 -* Обновили значение переменной `colorBgHighlight` `#FFF1AD` -* Настроили корректные тайпинги для этой переменной + +- Обновили значение переменной `colorBgHighlight` `#FFF1AD` +- Настроили корректные тайпинги для этой переменной ## 1.10.0 -* Добавили переменные для ширины и высоты больших кнопок ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/-/blob/master/themes/descriptions.ts#L858-868)) -* Добавили тему `calls` + +- Добавили переменные для ширины и высоты больших кнопок ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/-/blob/master/themes/descriptions.ts#L858-868)) +- Добавили тему `calls` ## 1.9.0 -* Минорное обновление цветов ошибки и саксеса. Утверждено с дизайнерами + +- Минорное обновление цветов ошибки и саксеса. Утверждено с дизайнерами ## 1.8.0 -* Добавили переменную `paddingPopupBase` ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/blob/master/themes/descriptions.ts#L1062)) -* Добавили переменную `paddingPopupHeader` ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/blob/master/themes/descriptions.ts#L1068)) -* Исправили SCSS сборку темы. Заменили классы на `mixin`, корректно обрабатывает desktop/mobile статические переменные. +- Добавили переменную `paddingPopupBase` ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/blob/master/themes/descriptions.ts#L1062)) +- Добавили переменную `paddingPopupHeader` ([описание](https://gitlab.corp.mail.ru/UX/paradigm.tokens/blob/master/themes/descriptions.ts#L1068)) +- Исправили SCSS сборку темы. Заменили классы на `mixin`, корректно обрабатывает desktop/mobile статические переменные. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e3c0c1a..e7acb225 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,16 +6,20 @@ Чтобы ваши изменения попали в основную ветку (master) нужно, чтобы ваш pull request одобрил кто-то из мейнтейнеров репозитория: -* [@vileven](https://github.com/vileven) -* [@8coon](https://github.com/8coon) -* [@warprobot](https://github.com/warprobot) +- [@vileven](https://github.com/vileven) +- [@8coon](https://github.com/8coon) +- [@warprobot](https://github.com/warprobot) Перед отправкой pull request-а на ревью убедитесь, что: -* в вашей ветке работает сборка (`npm run build:local`), -* в вашей ветке проходят тесты (`npm test`), -* покрытие тестов не ниже минимального значения, -* если вы вносили изменения в задокументированные части библиотеки, - ваш pull request содержит обновления документации. + +- в вашей ветке работает сборка (`npm run build:local`), +- в вашей ветке проходят тесты (`npm test`), +- в вашей ветке проходит линтер (`npm run lint`), некоторые ошибки можно автоматически поправить с помощью `npm run lint:fix`, +- покрытие тестов не ниже минимального значения, +- если вы вносите изменения в задокументированные части библиотеки, + ваш pull request содержит обновления документации, +- если вы вносите изменения в сами токены, вы + согласовали их с дизайнерами. Для разработки в репозитории может понадобиться установить [nodejs](https://nodejs.org/) не ниже версии 16. @@ -23,72 +27,84 @@ pull request одобрил кто-то из мейнтейнеров репоз Если вы вносили изменения в цвета, необходимо обновить [снапшоты тестов Jest](https://jestjs.io/ru/docs/snapshot-testing): -```npm test -- -u``` +`npm test -- -u` + +(Необязательно) Для игнорирование коммитов в `git blame`, связанные с +изменениями стиля кода, необходимо запустить следующую команду: + +```sh +git config --local blame.ignoreRevsFile .git-blame-ignore-revs +``` ## Версионирование В целом версионирование vkui-tokens придерживается [semver](https://semver.org/lang/ru/). -Пример формирования новой версии в зависимости от изменений: +Критерии формирования новой версии в зависимости от изменений перечислены ниже. -* локальное изменение цветов без изменения прозрачности -* локальное обратно совместимое изменение размеров +#### Поднимаем **патч**, если: -— Поднимаем **ПАТЧ** +- локальное изменение цветов без изменения прозрачности +- локальное обратно совместимое изменение размеров -* изменение прозрачности цветов (например rgb -> rgba) -* локальное изменение размеров в рамках ограниченного числа тем - (в release notes обязательно указать, какие токены изменились) -* добавление нового токена или новой темы -* обратно совместимые изменения инфраструктуры +#### Поднимаем минор, если: -— Поднимаем **МИНОР** +- изменение прозрачности цветов (например rgb -> rgba) +- локальное изменение размеров в рамках ограниченного числа тем + (в release notes обязательно указать, какие токены изменились) +- добавление нового токена или новой темы +- обратно совместимые изменения инфраструктуры -* изменение размеров большого числа токенов -* удаление токена или темы -* другие обратно-несовместимые изменение +#### Поднимаем мажор, если: -— Поднимаем **МАЖОР** +- изменение размеров большого числа токенов +- удаление токена или темы +- другие обратно-несовместимые изменение ## Структура репозитория -* src - * **interfaces** — описание интерфейса токенов - * `general` — описание общих типов и структур дизайн-системы - * `napespaces` — пространства имён тем оформления (vk, paradigm) - * `themes` — описание интерфейса каждой темы оформления - * **themeDescriptions** — описание конкретных значений переменных тем оформления - * _base_ — значения переменных базовых тем - * _themes_ — значения переменных продуктовых тем - * _common_ — вспомогательный код и общие для всех тем значения - * **build** — инструменты сборки - * **lint** — инструменты линтинга токенов +- src + - **interfaces** — описание интерфейса токенов + - `general` — описание общих типов и структур дизайн-системы + - `napespaces` — пространства имён тем оформления (vk, paradigm) + - `themes` — описание интерфейса каждой темы оформления + - **themeDescriptions** — описание конкретных значений переменных тем оформления + - _base_ — значения переменных базовых тем + - _themes_ — значения переменных продуктовых тем + - _common_ — вспомогательный код и общие для всех тем значения + - **build** — инструменты сборки + - **lint** — инструменты линтинга токенов ### Структура наследования тем -* _vkBase_ - * vkBaseDark - * vkCom - * vkIOS -* _paradigmBase_ - * paradigmBaseDark - * calendar - * calendarDark - * calls - * cloud - * home - * homeDark - * media - * mediaDark - * mycom - * octavius - * octaviusCompact - * octaviusCompactDark - * octaviusDark - * octaviusVK - * octaviusVKDark - * octaviusWhite - * otvet - * otvetDark - * pharma - * promo + +- _vkBase_ + - vkBaseDark + - vkCom + - vkIOS +- _paradigmBase_ + - paradigmBaseDark + - calendar + - calendarDark + - calls + - cloud + - home + - homeDark + - media + - mediaDark + - mycom + - octavius + - octaviusCompact + - octaviusCompactDark + - octaviusDark + - octaviusVK + - octaviusVKDark + - octaviusWhite + - otvet + - otvetDark + - pharma + - promo + - pulse + - pulseDark + - workspaceAdmin + - workspaceLandings diff --git a/README.md b/README.md index 905a0c8f..7d7d0236 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ [![Npm](https://img.shields.io/npm/v/@vkontakte/vkui-tokens)](https://www.npmjs.com/package/@vkontakte/vkui-tokens) [![GitHub Repo stars](https://img.shields.io/github/stars/VKCOM/vkui-tokens?label=GitHub%20Repo%20Stars&style=social)](https://github.com/VKCOM/vkui-tokens) -Этот репозиторий содержит токены единой дизайн-системы VKUI и -их значения для тем оформления различных проектов. +**[Интерактивная документация](https://vkcom.github.io/vkui-tokens/)** + +Этот репозиторий содержит токены единой дизайн-системы VKUI и их значения для тем оформления различных проектов. Темы собираются в следующие форматы: `css`, `scss`, `less`, `pcss`, `styl`, `js`, `json`. @@ -14,19 +15,19 @@ # Содержание -* [Использование](#использование) - * [Использование CSS-переменных темы напрямую из пакета](#использование-css-переменных-темы-напрямую-из-пакета) - * [Подключение темы на страницу](#подключение-темы-на-страницу) - * [Использование переменных в вёрстке](#использование-переменных-в-вёрстке) - * [Использование базовой темы напрямую из пакета](#использование-базовой-темы-напрямую-из-пакета) -* [Инструменты](#инструменты) - * [Локальная сборка своих тем инструментами библиотеки](#локальная-сборка-своих-тем-инструментами-библиотеки) - * [Наследование от существующей темы](#наследование-от-существующей-темы) - * [Создание собственной темы "с нуля"](#создание-собственной-темы-с-нуля) -* [Roadmap](#roadmap) -* [Полезные ссылки](#полезные-ссылки) -* [Информация для внесения изменений](CONTRIBUTING.md) -* [Changelog (архивная версия)](CHANGELOG.OLD.md) +- [Использование](#использование) + - [Использование CSS-переменных темы напрямую из пакета](#использование-css-переменных-темы-напрямую-из-пакета) + - [Подключение темы на страницу](#подключение-темы-на-страницу) + - [Использование переменных в вёрстке](#использование-переменных-в-вёрстке) + - [Использование базовой темы напрямую из пакета](#использование-базовой-темы-напрямую-из-пакета) + - [Создание новой темы для вашего проекта](docs/articles/new-theme/INDEX.md) +- [Инструменты](#инструменты) + - [Локальная сборка своих тем инструментами библиотеки](#локальная-сборка-своих-тем-инструментами-библиотеки) + - [Наследование от существующей темы](#наследование-от-существующей-темы) +- [Roadmap](#roadmap) +- [Полезные ссылки](#полезные-ссылки) +- [Информация для внесения изменений](CONTRIBUTING.md) +- [Changelog (архивная версия)](CHANGELOG.OLD.md) Актуальный changelog находится на странице [релизов в GitHub](https://github.com/VKCOM/vkui-tokens/releases)! @@ -34,53 +35,64 @@ # Использование Устанавливаем npm-пакет `@vkontakte/vkui-tokens`: + ```bash npm i --save @vkontakte/vkui-tokens@latest ``` + ## Использование CSS-переменных темы напрямую из пакета + ### Подключение темы на страницу В любом CSS-файле подключаем файл темы со значениями переменных: + ```css -@import "@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css"; +@import '@vkontakte/vkui-tokens/themes/vkBase/cssVars/declarations/index.css'; ``` ### Использование переменных в вёрстке + #### Использование в CSS + ```postcss -.myAwesomeClass:hover { - background-color: var(--vkui--color_background--hover); +.class:hover { + background-color: var(--vkui--color_background--hover); } ``` #### Использование CSS-переменных через объект в JavaScript (TypeScript) + ```typescript import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase/cssVars/theme'; // Собствено имя CSS-переменной (название токена) -console.log(baseTheme.colorBackground.hover.name) // --vkui--color_background--hover; +console.log(baseTheme.colorBackground.hover.name); // --vkui--color_background--hover; // Сниппет для использования CSS-переменной -console.log(baseTheme.colorBackground.hover.value) // var(--vkui--color_background--hover, #F5F5F7) +console.log(baseTheme.colorBackground.hover.value); // var(--vkui--color_background--hover, #F5F5F7) // Динамически (с учётом возможных переопределений) // узнаём, чему равно значение переменной внутри myElement: -getComputedStyle(myElement).getPropertyValue(baseTheme.colorBackground.hover.name) +getComputedStyle(myElement).getPropertyValue(baseTheme.colorBackground.hover.name); ``` #### Принудительное использование токенов определённого размера -Чтобы принудительно включить тот или иной вид темы у конкретного -поддерева элементов, нужно воспользоваться классами + +Чтобы принудительно включить тот или иной вид темы у конкретного +поддерева элементов, нужно воспользоваться классами `.vkui--force-${auto | regular | compact | large | largeX ...}`. -Смотри [демо](demo/example-adaptive-css-vars-theme.html) работы +Смотри [демо](demo/example-adaptive-css-vars-theme.html) работы адаптивных переменных и спец. классов. -Также можно просто использовать переменную конкретного брейкпоинта -(ex. --vkui--size_field_height--**_compact_**), они все тоже +Также можно просто использовать переменную конкретного брейкпоинта +(ex. --vkui--size*field_height--\*\*\_compact*\*\*), они все тоже попадают в `:root`) ## Использование базовой темы напрямую из пакета + ### js/ts/json + Импортируем необходимую тему в файле и используем: + ```ts import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase'; @@ -88,64 +100,77 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase'; ``` ### Используем в scss/styl/less root темы из пакета + Импортируем файл с необходимой темой и используем переменные от туда (снизу синтаксис SCSS) + ```scss -@import "~@vkontakte/vkui-tokens/themes/vkBase/index"; +@import '~@vkontakte/vkui-tokens/themes/vkBase/index'; .myAwesomeClass { - background-color: $color-bg; + background-color: $color-bg; } .myAwesomeClass:hover { - background-color: $color-bg--hover; + background-color: $color-bg--hover; } ``` -### Используем pcss формат темы из пакета +### Используем pcss формат темы из пакета -1Заходим в файл, где хотим использовать тему, и импортируем её: +1. Заходим в файл, где хотим использовать тему, и импортируем её: - @import "@vkontakte/vkui-tokens/themes/vkBase"; + ```css + @import '@vkontakte/vkui-tokens/themes/vkBase'; + ``` -2. Заходим в файл темы, смотрим какие там есть переменные и юзаем их, например: +2. Заходим в файл темы, смотрим какие там есть переменные и используем их, например: - width: var(--size-content-block-width); + ```css + width: var(--size-content-block-width); + ``` 3. Просто так ничего не заработает, нужно поставить postcss: - npm i --save-dev postcss + ```bash + npm i --save-dev postcss + ``` Для запуска у postcss есть командная строка, которую тоже надо установить: - npm i --save-dev postcss-cli + ```bash + npm i --save-dev postcss-cli + ``` 4. Создаем конфиг postcss. Для этого создаем файл postcss.config.js (можно в любом месте проекта, но лучше в корне) и пишем в него необходимые плагины: - ```javascript - const postcssPresetEnv = require('postcss-preset-env'); - - module.exports = { - plugins: [ - require('postcss-import'), - require('precss'), - require('postcss-css-variables'), - require('postcss-custom-media'), - require('postcss-media-minmax'), - require('postcss-extend-rule'), - postcssPresetEnv({ - stage: 0, - }), - require('postcss-color-mix'), - require('cssnano') - ], - }; - ``` + ```javascript + const postcssPresetEnv = require('postcss-preset-env'); + + module.exports = { + plugins: [ + require('postcss-import'), + require('precss'), + require('postcss-css-variables'), + require('postcss-custom-media'), + require('postcss-media-minmax'), + require('postcss-extend-rule'), + postcssPresetEnv({ + stage: 0, + }), + require('postcss-color-mix'), + require('cssnano'), + ], + }; + ``` + Возможно, вам не понадобятся все эти плагины, поэтому лучше почитать, что делает каждый из них (https://www.postcss.parts/). Нужно посмотреть файл вашей темы и ваш css (scss и др.), чтобы понять, что вам необходимо. 5. Устанавливаем все необходимые плагины, которые написали в конфиге, например: - npm i --save-dev postcss-import + ```bash + npm i --save-dev postcss-import + ``` 6. Настраиваем сборку postcss. @@ -154,102 +179,106 @@ import baseTheme from '@vkontakte/vkui-tokens/themes/vkBase'; Пример команды: - postcss src/main.css -c ./ --dir public + ```bash + postcss src/main.css -c ./ --dir public + ``` Такая команда прогонит файл src/main.css с помощью конфига из текущей папки и положит результат в папку public. # Инструменты -## Локальная сборка своих тем инструментами библиотеки - -Библиотека предоставляет интерфейсы и темы, от которых можно -наследоваться. - -Помимо этого, библиотека предоставляет набор функций, которые позволяют -собрать собственную тему в нужном формате. -Сборка темы подразумевает раскрытие наследования, генерацию цветов -состояний (hover, active), округление и "пикселизация" значений и т.д. +## Локальная сборка своих тем инструментами библиотеки -### Наследование от существующей темы -Пример: +Библиотека предоставляет интерфейсы и темы, от которых можно наследоваться, и набор функций, которые позволяют собрать собственную тему в нужном формате. -```typescript -import type {ThemeDescription} from '@vkontakte/vkui-tokens/interfaces/general'; -import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools'; -import {lightTheme as baseTheme} from '@vkontakte/vkui-tokens/themeDescriptions/base/vk'; -import {expandAll} from '@vkontakte/vkui-tokens/build/expandTheme'; -import {compileStyles} from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles'; +Сборка темы подразумевает раскрытие наследования, генерацию цветов состояний (hover, active), округление и "пикселизация" значений и т.д. -interface MyNewAwesomeThemeDescription extends ThemeDescription { - myNewAwesomeToken: Adaptive; -} +## Предварительная настройка -const myNewAwesomeTheme: MyNewAwesomeThemeDescription = { - ...baseTheme, - myNewAwesomeToken: { - regular: 20, - compact: 12, - }, -}; +Инструменты адаптированы для запуска в `Node`-среде, и не подходят для генерации темы в рантайме (в браузерной среде). +Вам необходимо установить следующие пакеты для корректной работы скриптов генерации: -// получаем разные типы тем на основе описания -const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme); - -// получаем CSS-строку со всеми переменными темы, -// которую можно вставить в DOM или сохранить в файл -const cssString = compileStyles('css', pixelifyTheme); +```bash +npm i --save-dev color common-tags css.escape ``` -### Создание собственной темы "с нуля" -В некоторых случаях нет необходимости наследоваться от одной из -базовых тем. Библиотека позволяет сгенерировать свою тему из -произвольного количества уникальных переменных. +### Наследование от существующей темы -Пример: +Например, возьмем базовые темы (светлую и темную) и добавим к ним новый токен и переопределим один существующий. +Для этого нам нужно исполнить следующий скрипт: ```typescript -import type {Adaptive} from '@vkontakte/vkui-tokens/interfaces/general/tools'; -import {expandAll} from '@vkontakte/vkui-tokens/build/expandTheme'; -import {compileStyles} from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles'; +import type { ThemeDescription } from '@vkontakte/vkui-tokens/interfaces/general'; +import type { Adaptive } from '@vkontakte/vkui-tokens/interfaces/general/tools'; +import { + lightTheme as baseTheme, + darkTheme, +} from '@vkontakte/vkui-tokens/themeDescriptions/base/vk.js'; +import { expandAll } from '@vkontakte/vkui-tokens/build/expandTheme'; +import { compileStyles } from '@vkontakte/vkui-tokens/build/compilers/styles/compileStyles'; -interface MyNewAwesomeThemeDescription { - myNewAwesomeToken: Adaptive; +interface MyNewAwesomeThemeDescription extends ThemeDescription { + myNewAwesomeToken: Adaptive; } const myNewAwesomeTheme: MyNewAwesomeThemeDescription = { - myNewAwesomeToken: { - regular: 20, - compact: 12, - }, + ...baseTheme, + // Название темы + themeName: 'myAwesomeTheme', + // Базовая часть названия темы (используется для генерации локального селектора, например: .vkui--myAwesomeTheme--light) + themeNameBase: 'myAwesomeTheme', + // Тема, от которой наследуются переменные, носит информационный характер + themeInheritsFrom: 'vkBase', + // Новый адаптивный токен + myNewAwesomeToken: { + regular: 20, + compact: 12, + }, + colors: { + // Сохраняем остальные значения из темы + ...baseTheme.colors, + // Переопределяем необходимую переменную + colorTextAccentThemed: '#ff0000', + }, }; -// получаем разные типы тем на основе описания -const {theme, pixelifyTheme, cssVarsTheme} = expandAll(myNewAwesomeTheme); +const myNewAwesomeThemeDark: MyNewAwesomeThemeDescription = { + ...myNewAwesomeTheme, + ...darkTheme, + themeName: 'myAwesomeThemeDark', + themeNameBase: 'myAwesomeTheme', + themeInheritsFrom: 'vkBaseDark', + colors: { + ...darkTheme.colors, + colorTextAccentThemed: '#00ff00', + }, +}; -// получаем CSS-строку со всеми переменными темы, -// которую можно вставить в DOM или сохранить в файл -// буквально тут содержится: -/* -:root { - --vkui--my_new_awesome_token--regular: 20px; - --vkui--my_new_awesome_token--compact: 12px; -} - */ +// Получаем разные типы тем на основе описания +const { theme, pixelifyTheme, cssVarsTheme } = expandAll(myNewAwesomeTheme); +const { pixelifyTheme: pixelifyThemeDark } = expandAll(myNewAwesomeThemeDark); + +// Для использования, например, в вебе вам подойдет компиляция "пикселяризованной" темы в формате '.css': const cssString = compileStyles('css', pixelifyTheme); +const cssStringDark = compileStyles('css', pixelifyThemeDark); + +// Полученные CSS-строки со всеми переменными тем можно вставить в DOM или сохранить в файл ``` # Roadmap -* [ ] Добавить более умную генерацию active, hover состояний цвета. - При генерации нужно учитывать тёмный и светлый вариант тем, а также - сам цвет, для которого генерируется состояние. - (решаем проблему, что цвет наведения, сгенерированный от синего, - плохо виден на большинстве мониторов). -* [ ] Генерация цветов по заранее определённой палитре. -* [ ] Текстовое описание семантики каждого токена. -* [ ] Более подробная документация. -* [ ] Сайт с примерами и описанием. + +- [ ] Добавить более умную генерацию active, hover состояний цвета. + При генерации нужно учитывать тёмный и светлый вариант тем, а также + сам цвет, для которого генерируется состояние. + (решаем проблему, что цвет наведения, сгенерированный от синего, + плохо виден на большинстве мониторов). +- [ ] Генерация цветов по заранее определённой палитре. +- [ ] Текстовое описание семантики каждого токена. +- [ ] Более подробная документация. +- [ ] Сайт с примерами и описанием. # Полезные ссылки + 1. [Доклад](https://youtu.be/0rHgqQvl0NQ?t=1858) про дизайн-системы на фронтенде: там рассказывается, зачем нужны дизайн-токены, причём тут UI-kit и как делать темизацию. 2. Серия видеороликов на youtube, где показано использование этой библиотеки (но со старым названием, не пугайтесь), как ядра дизайн-системы на практике: [первый](https://www.youtube.com/watch?v=RKCsrPOxYWE), [второй](https://www.youtube.com/watch?v=ZhiH4jFL-kU), [третий](https://www.youtube.com/watch?v=ZXOmmkyxrwk) 3. Opensource библиотека компонентов (UI-kit) [VKUI](https://github.com/VKCOM/VKUI), которая использует токены. diff --git a/docs/articles/new-theme/INDEX.md b/docs/articles/new-theme/INDEX.md new file mode 100644 index 00000000..cb81e45d --- /dev/null +++ b/docs/articles/new-theme/INDEX.md @@ -0,0 +1,108 @@ +# Создание новой темы для вашего проекта + +Если вы хотите использовать токены VKUI не только в связке с основной библиотекой, но и в +произвольной вёрстке, у вас может возникнуть потребность расширения стандартного набора. + +Для расширения стандартного набора токенов и создания **локальных** токенов вашего проекта нужно +завести под ваш проект отдельную тему. + +По согласованию с +[мейнтейнерами](https://github.com/VKCOM/vkui-tokens/blob/master/CONTRIBUTING.md) +репозитория, вы можете завести тему проекта прямо здесь, в `@vkontakte/vkui-tokens`. + +## Подготовка + +Прежде, чем заводить свою тему, вам нужно ответить для себя на следующий вопрос: + +_Какая из базовых тем будет являться основной для вашего проекта?_ + +Выбор базовой темы влияет на внешний вид вашего проекта в тех местах, которые вы не поправите +в своей теме. + +Базовыми являются две темы: `paradigm` и `vk`. Помочь с выбором базовой темы вам могут дизайнеры. + +Использовать в качестве базовой темы проектов (например, `octavius`) **нельзя**. + +## Внесение правок + +Для заведения новой темы потребуется завести следующие файлы: + +- `src/interfaces/themes/<имя темы>/index.ts` — описание типов темы; +- `src/themeDescriptions/themes/<имя темы>/index.ts` — конкретные значения токенов темы. + +После чего новую тему нужно будет правильно экспортировать и поправить доку. + +### Описание типов + +В файле декларации типов описываются **локальные токены** — +токены, которыми ваша тема будет отличаться от базовой. + +Названия локальных токенов должны начинаться с префикса имени вашей темы: например +`octaviusColorBackground`. + +Пример декларации типов темы, наследованной от базовой темы `paradigm`: + +```typescript +import { ThemeCssVars } from '@/interfaces/general'; +import { ParadigmTheme, ParadigmThemeDescription } from '@/interfaces/namespaces/paradigm'; + +export interface ThemeWorkspaceAdmin extends ParadigmTheme {} + +export interface ThemeWorkspaceAdminDescription extends ParadigmThemeDescription {} + +export interface ThemeWorkspaceAdminCssVars + extends ThemeCssVars {} +``` + +Пример декларации типов темы, наследованной от базовой темы `vk`: + +```typescript +import { Theme, ThemeCssVars, ThemeDescription } from '@/interfaces/general'; + +export interface ThemeVkBase extends Theme {} +export interface ThemeVkBaseDescription extends ThemeDescription {} + +export interface ThemeVkBaseCssVars extends ThemeCssVars {} +``` + +Для примера темы с большим количеством локальный токенов можно посмотреть на тему +[octavius](https://github.com/VKCOM/vkui-tokens/blob/master/src/interfaces/themes/octavius/index.ts). + +### Указание значений токенов + +В файле имплементации описываются конкретные значения, которые будут принимать токены вашей темы. + +Пример темы с наследованием от базовой светлой темы `paradigm`: + +```typescript +import { ThemeWorkspaceAdminDescription } from '@/interfaces/themes/workspaceAdmin'; +import { lightTheme } from '@/themeDescriptions/base/paradigm'; + +export const workspaceAdminTheme: ThemeWorkspaceAdminDescription = { + ...lightTheme, + themeName: 'workspaceAdmin', + themeNameBase: 'workspaceAdmin', +}; +``` + +Посмотреть, как сделана, например, тёмная тема можно на примере темы +[octavius](https://github.com/VKCOM/vkui-tokens/blob/master/src/themeDescriptions/themes/octavius/index.ts). + +_Обратите внимание_. К значениям локальных токенов применяются всё те же правила линтинга, что +и к значениям токенов в базовой теме: например, нельзя завести цвет с прозрачностью в токене, +в названии которого не отражён факт прозрачности (через постфикс Alpha, Opacity и прочие). + +То есть иными словами, токен `octaviusBackgroundCompose: 'rgba(51, 51, 51, .4)'` не пройдёт +проверку линтером, а токен `octaviusBackgroundComposeAlpha: 'rgba(51, 51, 51, .4)'` — +пройдёт. + +### Экспорт темы и документация + +Для экспорта темы необходимо указать её в файле `src/themeDescriptions/index.ts`. + +Также не забудьте поправить список тем в документации: `CONTRIBUTING.md`. + +## Пример + +Пример добавления темы продукта: +[workspaceAdmin](https://github.com/VKCOM/vkui-tokens/pull/483/files). diff --git a/docs/docs.d.ts b/docs/docs.d.ts new file mode 100644 index 00000000..976923f6 --- /dev/null +++ b/docs/docs.d.ts @@ -0,0 +1,4 @@ +declare module '*.svg' { + const content: any; + export default content; +} diff --git a/docs/public/index.html b/docs/public/index.html new file mode 100644 index 00000000..104bb926 --- /dev/null +++ b/docs/public/index.html @@ -0,0 +1,18 @@ + + + + + + + + + + VKUI Tokens documentation + + +
+ + diff --git a/docs/public/static/meta/apple-touch-icon.png b/docs/public/static/meta/apple-touch-icon.png new file mode 100644 index 00000000..7f6a36bb Binary files /dev/null and b/docs/public/static/meta/apple-touch-icon.png differ diff --git a/docs/public/static/meta/favicon.ico b/docs/public/static/meta/favicon.ico new file mode 100644 index 00000000..63facf02 Binary files /dev/null and b/docs/public/static/meta/favicon.ico differ diff --git a/docs/public/static/svg/logo.svg b/docs/public/static/svg/logo.svg new file mode 100644 index 00000000..1116750c --- /dev/null +++ b/docs/public/static/svg/logo.svg @@ -0,0 +1,24 @@ + + + + + + diff --git a/docs/src/App.tsx b/docs/src/App.tsx new file mode 100644 index 00000000..8ed21fbb --- /dev/null +++ b/docs/src/App.tsx @@ -0,0 +1,15 @@ +import '@vkontakte/vkui/dist/vkui.css'; +import './styles/index.css'; + +import React, { FC } from 'react'; + +import Main from '@/components/layouts/Main'; +import Tokens from '@/pages/Tokens'; + +const App: FC = () => ( +
+ +
+); + +export default App; diff --git a/docs/src/components/layouts/Main.tsx b/docs/src/components/layouts/Main.tsx new file mode 100644 index 00000000..14cbb269 --- /dev/null +++ b/docs/src/components/layouts/Main.tsx @@ -0,0 +1,33 @@ +import { + AdaptivityProvider, + Appearance, + AppRoot, + ConfigProvider, + Panel, + SizeType, + View, +} from '@vkontakte/vkui'; +import React, { FC } from 'react'; + +import Header from './shared/Header/Header'; + +type Props = { + children: React.ReactNode; +}; + +const Main: FC = ({ children }) => ( + + + + + +
+
{children}
+ + + + + +); + +export default Main; diff --git a/docs/src/components/layouts/shared/Header/Header.tsx b/docs/src/components/layouts/shared/Header/Header.tsx new file mode 100644 index 00000000..20117980 --- /dev/null +++ b/docs/src/components/layouts/shared/Header/Header.tsx @@ -0,0 +1,29 @@ +import { Card, PanelHeader, useAdaptivityWithJSMediaQueries } from '@vkontakte/vkui'; +import clsx from 'clsx'; +import React, { FC } from 'react'; + +import { LogoIcon } from '@/shared/content/icons'; + +import Navigation from '../Navigation/Navigation'; + +const Header: FC = () => { + const { viewWidth } = useAdaptivityWithJSMediaQueries(); + const isTabletPlus = viewWidth > 3; + + return ( + + +
+
+ +
+ {isTabletPlus && } +
+ + + ); +}; + +export default Header; diff --git a/docs/src/components/layouts/shared/Navigation/Navigation.content.ts b/docs/src/components/layouts/shared/Navigation/Navigation.content.ts new file mode 100644 index 00000000..074aa92b --- /dev/null +++ b/docs/src/components/layouts/shared/Navigation/Navigation.content.ts @@ -0,0 +1,26 @@ +type NavigationItem = { + text: string; + href?: string; +}; + +export const navigation: Array = [ + { + text: 'Документация', + href: 'https://vkcom.github.io/VKUI/', + }, + { + text: 'Компоненты', + href: 'https://vkcom.github.io/VKUI/#/SplitLayout', + }, + { + text: 'Токены', + }, + { + text: 'Иконки', + href: 'https://vkcom.github.io/icons/', + }, + { + text: 'Github', + href: 'https://github.com/VKCOM/VKUI', + }, +]; diff --git a/docs/src/components/layouts/shared/Navigation/Navigation.tsx b/docs/src/components/layouts/shared/Navigation/Navigation.tsx new file mode 100644 index 00000000..fdb53506 --- /dev/null +++ b/docs/src/components/layouts/shared/Navigation/Navigation.tsx @@ -0,0 +1,32 @@ +import { Button } from '@vkontakte/vkui'; +import React, { FC } from 'react'; + +import { navigation } from './Navigation.content'; + +const styles = { + selected: { + background: 'rgba(0, 0, 0, 0.04)', + opacity: '100', + }, +}; + +const Navigation: FC = () => ( +
+ {navigation.map((item) => ( + + ))} +
+); + +export default Navigation; diff --git a/docs/src/components/pages/Tokens/TokensActions/TokensActions.content.tsx b/docs/src/components/pages/Tokens/TokensActions/TokensActions.content.tsx new file mode 100644 index 00000000..9f6b306e --- /dev/null +++ b/docs/src/components/pages/Tokens/TokensActions/TokensActions.content.tsx @@ -0,0 +1,15 @@ +import { Icon20ComputerOutline, Icon20SmartphoneOutline } from '@vkontakte/icons'; +import React from 'react'; + +export const valueTypes = [ + { + 'label':