Usage of Polymer 1.0 paper-styles Element

6
votes

Unfortunately, I'm finding the current documentation/examples for the usage of paper-styles a bit lacking. I'm not an experienced CSS guy (relative newbie actually), so I could really use examples of how to implement Polymer 1.0 application-wide styling in order to be used by all of it's custom elements (i.e. by applying classes to any tags in those custom element's local DOMs). I did this kind of thing relatively easily in Polymer 0.5 using core-styles, but it has changed enough in 1.0 to confuse me, particularly without full docs/examples to work from. It also seems there may be a few ways to accomplish this. I'm also wondering if paper-styles is still considered experimental in 1.0? There are no docs or examples for it's use in polymer 1.0 online element catalog (https://elements.polymer-project.org/elements/paper-styles), although I did come across 'some' on it's gitHub repository.

2
polymerpolymer-1.0paper-elements
paper-styles is just similar to an app-theme.html file. You just import it on your project and the custom properties it defines will be applied and/or can be used. – Neil John Ramal

2 Answers

4
votes

One thing you can do when documentation is lacking is search through other projects that are using the code you would like to use. paper-tabs, for example, uses paper-styles. You can see an example import of paper-styles/color.html in paper-tabs.html. The value --paper-yellow-a100 is being used in paper-tabs.html. Below is an example of using various CSS variables (var) and mixins (@apply) defined in paper-styles to apply style to the main document.

<!DOCTYPE html>
<html>
<head>
    <title>paper-styles Example</title>
    <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
    <link rel="import" href="bower_components/polymer/polymer.html" />
    <link rel="import" href="bower_components/paper-styles/paper-styles.html" />
    <style is="custom-style">
        .shadow {
            @apply(--shadow-elevation-16dp);
        }

        section {
            background-color: var(--google-blue-700);
        }

        p {
            @apply(--paper-font-display3);
        }
    </style>
</head>
<body>
    <section class="shadow">
        <h1>Example</h1>
        <p>
            This is an example using <em>paper-styles</em>.
        </p>
    </section>
</body>
</html>

Click here to learn more about styling in Polymer 1.0.


Concerning your question about paper-styles being experimental, on the Polymer home page in the catalog section it states:

Custom elements, built by the Polymer team, ready to use in your applications.

However, in various locations on the site, including styling, there are mentions of experimental features.

the custom properties shim included in Polymer includes an experimental extension

At this time using @apply would be considered experimental.

There is a page on the Polymer website titled Experimental features & elements you can look at for more information.

5
votes

The general misunderstanding seems to be, that just by importing the paper-styles element, the document gets styled according to the material design specs. That's not the case.

You just get all the variables and mixins.

Then you need to apply them to each and every element inside your custom-element the way you see it fit.

Here is an example element:

<dom-module id="demo-element">
    <template>
        <style>
            :host {
                display: block;
                background: var(--paper-blue-500);
                padding: 20px;
            }

            .title { @apply(--paper-font-title); }

            button { @apply(--paper-font-button); }     
        </style>

        <h1 class="title">Hello World</h1>

        <button>Demo</button>

    </template>
    <script>
        Polymer({
            is: 'demo-element'
        });
    </script>
</dom-module>

Luckily the styles are nicely structured inside just four files with each just a couple of hundred lines max.