{"id":22998278,"url":"https://github.com/uswitch/ustyle","last_synced_at":"2025-08-14T00:32:06.546Z","repository":{"id":10203394,"uuid":"12296737","full_name":"uswitch/ustyle","owner":"uswitch","description":"A living styleguide and pattern library by uSwitch.","archived":false,"fork":false,"pushed_at":"2024-02-07T19:28:52.000Z","size":33546,"stargazers_count":19,"open_issues_count":47,"forks_count":5,"subscribers_count":52,"default_branch":"master","last_synced_at":"2024-04-14T04:27:50.790Z","etag":null,"topics":["css","front-end","sass","styleguide","uswitch"],"latest_commit_sha":null,"homepage":"https://ustyle.guide","language":"Smarty","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uswitch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-08-22T12:47:30.000Z","updated_at":"2024-06-19T11:29:03.223Z","dependencies_parsed_at":"2023-02-15T04:31:51.409Z","dependency_job_id":"9741a5dd-2abd-4f4f-8d9e-0bfe907ce250","html_url":"https://github.com/uswitch/ustyle","commit_stats":{"total_commits":1650,"total_committers":56,"mean_commits":"29.464285714285715","dds":0.4927272727272727,"last_synced_commit":"f0b1011a33fa6241cdc3eece9a7d7c9a577e7c3e"},"previous_names":[],"tags_count":191,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fustyle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fustyle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fustyle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fustyle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uswitch","download_url":"https://codeload.github.com/uswitch/ustyle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229474388,"owners_count":18078547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","front-end","sass","styleguide","uswitch"],"created_at":"2024-12-15T06:12:35.991Z","updated_at":"2024-12-15T06:12:36.578Z","avatar_url":"https://github.com/uswitch.png","language":"Smarty","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [ustyle](http://ustyle.guide)\n\n![ustyle unicorn](https://assets0.uswitch.com/s3/uswitch-assets-eu/ustyle/ustyle-unicorn.png)\n\nuStyle, aptly named, is the styleguide gem for [uSwitch](http://www.uswitch.com). Include it in your Rails/Sinatra/Anything project as a gem to apply consistent styles according the uSwitch styleguide.\n\nThis project is provided as is and is aimed at building uSwitch specific projects.\n\n* [Features](#features)\n* [Infrastructure](#infrastructure)\n* [Installation](#installation)\n  * [Sinatra](#sinatra)\n* [Usage](#usage)\n  * [Rails / Sprockets apps](#rails--sprockets-apps)\n  * [Node apps](#node-apps)\n  * [Mixins/Variables](#mixins--variables)\n* [Development](#development)\n* [Contributing](#contributing)\n\n## Features\n\nuStyle is a fully fledged living styleguide that delivers both CSS and JavaScript components for technical implementations as well as documentation for how these things should be applied across uSwitch.\n\n* [Pattern library](https://ustyle.guide/pattern-library/index.html)\n* [Design guidelines](https://ustyle.guide/design/index.html)\n* [Brand guidelines](https://ustyle.guide/brand/index.html)\n\n## Infrastructure\n\nuStyle is compiled and uploaded to S3. Consequently it is served from Cloudfront via our nginx load balancers.\n\nuStyle within applications is usually served within their asset pipeline on compilation.\n\n## Installation\n\nPre-requisites:\n\nIf you want to use as a gem\n\n* Ruby (1.9+)\n* Sinatra / Rails applications with sprockets\n\nThis can also be used as a node package just like you would install any other package.\n\nuStyle automagically sets itself up in a sprockets context where found. That means both Sinatra and Rails apps get configured correctly. However there are a few gotchas, as we don't want to add gem dependencies that are only required for certain set ups.\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'ustyle'\n```\n\nAnd then run in your terminal:\n\n    $ bundle\n\n### Sinatra\n\nAdd to your Gemfile:\n``` ruby\ngem 'sprockets'\ngem 'sprockets-sass', '~\u003e 1.2.0'\ngem 'sprockets-helpers'\n```\n\nThen in your app file (usually named server.rb/app.rb etc), after declaring your `class App \u003c Sinatra::Base`:\n\n```ruby\nregister Sinatra::Ustyle\n```\n\n**You must use `sprockets-sass` version 1.1.0 or above, as there was a bug where the postprocessor was getting added to the preprocessor which caused autoprefixer to break**\n\nThis is only for the gem, not the styleguide within this project.\n\n### Icons\n\nuStyle serves it's icons via `\u003cuse xlink:href\u003e\u003c/use\u003e` tags within an SVG. We have decided to not embed our SVGs, but rather serve them from a URL. See here for a better explanation: https://css-tricks.com/svg-use-with-external-reference-take-2/\n\nDue to this, you need to have the `icons.svg` symbol map on the same domain, protocol and port as your application. To facilite this without serving a sprockets asset, ustyle comes with some `Rack Middleware`\n\nFor Rails apps, in your `development.rb` file (you do not want this in production)\n```ruby\nconfig.middleware.use Ustyle::IconMiddleware\n```\n\nFor Rack apps (including Sinatra)\n```ruby\nconfigure :development do\n  use Ustyle::IconMiddleware\nend\n```\n\nCurrently there is no middleware to support node apps, but can be written easily.\n\nAlternatively, you can serve your application in a docker container with nginx (or another supporting proxy server) that has a route to /icons.svg so you can proxy pass to our icons for the app. Ports, domains and protocols **must** match when testing the icons.\n\nAn example nginx configuration:\n```nginx\nlocation = /icons.svg {\n  set $upstream \"https://assets0.uswitch.com/s3/uswitch-assets-eu/ustyle\";\n  proxy_pass $upstream$request_uri;\n}\n```\n\nYou can then successfully reference your icon like so:\n\n```html\n\u003csvg role=\"img\" class=\"us-icon--medium us-icon--custom us-icon--{$NAME}\"\u003e\n  \u003cuse xlink:href=\"/images/icons.svg#icon-{$NAME}\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\n#### Adding a new Icon\n\nTo add a new Icon, add the SVG file to `/vendor/assets/images/icons`,\nthen add your new icon name as `@state icon` to [this\nfile](https://github.com/uswitch/ustyle/blob/new-shield-icon/vendor/assets/stylesheets/ustyle/icons/_base.scss#L19-L112).\n\nFinally, build the optimised icons using\n\n```sh\ngrunt icons\n```\n\n## Usage\n\n### Rails / Sprockets apps\n\nIf using Rails and Sass, just import the base uSwitch styles at the start of your file\n\n```scss\n@import \"ustyle\";\n```\n\nThis will import the main components. If you want more granular control of what to import, please look at the source code or the styleguide.\n\n### Node apps\n\nuStyle comes with JavaScript implementations of the custom Sass Ruby functions used by Sprockets. To use uStyle's mixins and variables within your own Sass, you'll need to add these functions to the compiler you're using. For example, using [node-sass](https://github.com/sass/node-sass) in a project that also has [Webpack](https://webpack.js.org/), you can do the following:\n\n```javascript\n// In your webpack.config.js\n\nimport { SassHelpers } from 'ustyle';\n\nmodule.exports = {\n  // ...\n  module: {\n    rules: [\n      // ...\n      {\n        test: /.scss$/,\n        use: [{\n          loader: 'sass-loader',\n          options: {\n            functions: SassHelpers\n          }\n        }]\n      }\n      // ...\n    ]\n  }\n  // ...\n};\n```\n\n### Mixins / Variables\n\nuStyle comes bundled with a good set of Sass variables and mixins to use in your project.\n\nFor Sass documentation on mixins/variables available to you, please see: https://ustyle.guide/sass/\n\n## Development\n\nTo preview changes that you make to uStyle's components and documentation, install dependencies with\n\n    $ npm install\n    \n    $ bundle install\n\nthen run:\n\n    $ npm start\n\nThis will run the [Grunt](http://gruntjs.com/) default task that builds uStyle, then starts a [Browsersync](https://www.browsersync.io/) server at http://localhost:3000. Changes that you make are live-reloaded in your browser.\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/uswitch/ustyle/blob/master/CONTRIBUTING.md)\n\n## Licences\n\n- Source code is licensed under the Apache v2.0 licence\n- All icons, except the uSwitch icon are licensed under [CC - Attribution - No Derivatives 4.0](http://creativecommons.org/licenses/by-nd/4.0/)\n- uSwitch icon is licensed under [CC - Attribution - NonCommercial - NoDerivates 4.0](http://creativecommons.org/licenses/by-nc-nd/4.0/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fustyle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuswitch%2Fustyle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fustyle/lists"}