{"id":18771032,"url":"https://github.com/rareloop/primer","last_synced_at":"2025-07-24T20:33:50.518Z","repository":{"id":35157199,"uuid":"39392806","full_name":"Rareloop/primer","owner":"Rareloop","description":"A Pattern Library written in PHP","archived":false,"fork":false,"pushed_at":"2019-11-28T10:30:02.000Z","size":192,"stargazers_count":43,"open_issues_count":3,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-04-28T00:42:52.601Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rareloop.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-20T15:44:07.000Z","updated_at":"2023-07-21T17:38:52.000Z","dependencies_parsed_at":"2022-09-16T15:02:17.524Z","dependency_job_id":null,"html_url":"https://github.com/Rareloop/primer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rareloop%2Fprimer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rareloop%2Fprimer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rareloop%2Fprimer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rareloop%2Fprimer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rareloop","download_url":"https://codeload.github.com/Rareloop/primer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223574836,"owners_count":17167569,"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":[],"created_at":"2024-11-07T19:22:54.637Z","updated_at":"2024-11-07T19:22:55.587Z","avatar_url":"https://github.com/Rareloop.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Primer\n[![Latest Stable Version](https://poser.pugx.org/rareloop/primer-core/v/stable)](https://packagist.org/packages/rareloop/primer-core)\n![CI](https://travis-ci.org/Rareloop/primer-core.svg?branch=master)\n![Coveralls](https://coveralls.io/repos/github/Rareloop/primer-core/badge.svg?branch=master)\n![Downloads](https://img.shields.io/packagist/dt/rareloop/primer-core.svg)\n\nPrimer is an extensible Design System/Pattern Library written in PHP. By default it utilises Twig for templating and Markdown/YAML for Documentation.\n\n## Installation\nTo create a new Primer project run the following command:\n\n`composer create-project rareloop/primer my-primer-folder --remove-vcs`\n\n## Usage\nThe easiest way to get up and running is to use the inbuilt PHP Standalone Server:\n\n`composer server`\n\nAnd then open the following URL in your browser `http://localhost:8080`.\n\nIf you need to specify the port you can pass this as an argument to the command:\n\n`composer server 1234`\n\n## Getting Started\n\nPrimer has three separate sections:\n\n1. [Documents](#documents) - A place to store the written documentation for your Design System.\n2. [Patterns](#patterns) - A Pattern Library that catalogues all the components within your system.\n3. [Templates](#templates) - A way to view the various Page Templates available in your system.\n\n## Patterns\n\nPatterns are the building blocks of your system and Primer provides a simple way to view your entire catalogue, a selection or just a single item. Patterns are located in the `resources/patterns` folder and are themselves a folder that contain all it's related files.\n\n### Anatomy of a pattern\n\nEach Pattern has an implicit `id` and `title`. \n\nThe `id` is the path used to identify it under the patterns folder, e.g. `elements/forms/input`.\n\nA patterns `title` is built from the name of the pattern's folder, e.g. `elements/lists/ordered-list` =\u003e `Ordered List`.\n\nEach pattern folder can contain the following:\n\n- **A template** A Twig template used to build the pattern's HTML (`template.twig`)\n- **One or more data files** A file to provide the state data required by the template file\n\n### State Data\n\nOut of the box, Primer supports State Data in two formats, PHP or JSON.\n\n#### PHP State Data\n\nPHP State Data files are named `data.php` and must return an array of key/values. This data is then passed to your Twig template at render time.\n\n```php\n\u003c?php\n\nreturn [\n    'title' =\u003e 'Page Title',\n];\n```\n\n#### JSON State Data\n\nState Data can also be provided as JSON files which are named `data.json`. This data is then passed to your Twig template at render time.\n\n```json\n{\n    \"title\": \"Page Title\"\n}\n```\n\n#### Alternative State Data\n\nWhen building a Pattern Library it is important to be able to easily test the different states a component can be in and Primer makes this easy. Alternative states can be provided by adding additional files to your Pattern folder in the format:\n\n`data~statename.(php|json)`\n\nFor example to show the error state for an input component you could create a file called `data~error.php`.\n\n### Including patterns within one another\n\nAny pattern can be included within another by using the standard Twig include and referencing the Pattern with it's `id`, e.g.\n\n```html\n{% include 'components/common/site-header' %}\n```\n\n## Templates\n\nTemplates can be built up using a mix of custom HTML and Pattern includes and are stored in `resources/templates`. If required additional grouping/nesting can be achieved by adding folders.\n\nAll templates should extend from `primer-base.twig` and your custom content should be added to the `templateContent` block, e.g.\n\n```\n{% extends 'primer-base.twig' %}\n\n{% block templateContent %}\n    \u003ch1\u003eExample Template\u003c/h1\u003e\n    \u003cp\u003eThis is an example page template that extends from the \u003ccode\u003eprimer-base.twig\u003c/code\u003e file.\u003c/p\u003e\n{% endblock %}\n```\n\n## Documents\n\nPrimer provides a simple way to present your Design System Documentation using MarkDown files.\n\nTo add a new Documentation Page, simply add a Markdown file (with the `.md` extension) to `resources/docs` folder. You can create grouping/nesting by including folders in the structure.\n\n### Meta Data\n\nBy default Primer will give your Page a title based on the filename but this can be overwritten by adding YAML FrontMatter to your file. For example, to specify the Title and Description you could do the following:\n\n```\n---\ntitle: Page Title\ndescription: This is a description\n---\n# Heading 1\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit. Hic placeat iusto animi architecto quasi, praesentium.\n```\n\nBoth `title` \u0026 `description` are keywords that Primer knows how to handle but you are free to add any additional meta data to the FrontMatter that you like. All Markdown files are also passed through the Twig Environment, so custom meta can be used to dynamically generate HTML.\n\n```\n---\ntitle: Page Title\ndescription: This is a description\ncolours:\n    - ff0000\n    - 00ff00\n    - 0000ff\n---\n# Colours\n\n\u003cul\u003e\n{% for colour in colours %}\n    \u003cli\u003e{{ colour }}\u003c/li\u003e\n{% endfor %}\n\u003c/ul\u003e\n\nThese are the colours we use!\n```\n\n## Adding Frontend Assets\n\nPrimer is un-opinionated about what Frontend stack you choose to use. Once you're ready to add CSS and JavaScript assets to your HTML, you should do this in the `views/primer-base.twig` file. This is a common ancestor that all Primer requests use which will ensure your Patterns and Templates will render as you'd expect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frareloop%2Fprimer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frareloop%2Fprimer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frareloop%2Fprimer/lists"}